home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / tex / macros / distribs / doc / doc.doc (.txt) < prev    next >
LaTeX Document  |  1992-09-07  |  191KB  |  4,123 lines
  1. % \iffalse meta-comment
  2. % Copyright (C) 1989-1992 by Frank Mittelbach.  All rights reserved.
  3. % This file is part of the doc package.
  4. % IMPORTANT NOTICE:
  5. % You are not allowed to change this file.  You may however copy
  6. % this file to a file with a different name and then change the
  7. % copy if you obey the restrictions on file changes described in
  8. % readme.mz.
  9. % You are NOT ALLOWED to distribute this file alone.  You are NOT
  10. % ALLOWED to take money for the distribution or use of this file
  11. % (or a changed version) except for a nominal charge for copying
  12. % etc.
  13. % You are allowed to distribute this file under the condition that
  14. % it is distributed together with all files mentioned in
  15. % readme.mz0.
  16. % If you receive only some of these files from someone, complain!
  17. % However, if these files are distributed by established suppliers
  18. % as part of a complete TeX distribution, and the structure of the
  19. % distribution would make it difficult to distribute the whole set
  20. % of files, *those parties* are allowed to distribute only some of
  21. % the files provided that it is made clear that the user will get
  22. % a complete distribution-set upon request to that supplier (not
  23. % me).  Notice that this permission is not granted to the end
  24. % user.
  25. % For error reports in case of UNCHANGED versions see readme.mz
  26. % \fi
  27. % ^^A -*-LaTeX-*-
  28. % ^^A These shouldn't come out in .ist files, hence the module
  29. % ^^A comments, or in the printed version, hence temporary comment
  30. % ^^A category for `<'
  31. %\catcode`\<=14
  32. %<*style>
  33. \def\fileversion{v1.7k} 
  34. \def\filedate{92/08/24}
  35. \def\docdate {92/08/28}
  36. %</style>
  37. %\catcode`\<=12
  38. % \CheckSum{1985}
  39. %% \CharacterTable
  40. %%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
  41. %%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
  42. %%   Digits        \0\1\2\3\4\5\6\7\8\9
  43. %%   Exclamation   \!     Double quote  \"     Hash (number) \#
  44. %%   Dollar        \$     Percent       \%     Ampersand     \&
  45. %%   Acute accent  \'     Left paren    \(     Right paren   \)
  46. %%   Asterisk      \*     Plus          \+     Comma         \,
  47. %%   Minus         \-     Point         \.     Solidus       \/
  48. %%   Colon         \:     Semicolon     \;     Less than     \<
  49. %%   Equals        \=     Greater than  \>     Question mark \?
  50. %%   Commercial at \@     Left bracket  \[     Backslash     \\
  51. %%   Right bracket \]     Circumflex    \^     Underscore    \_
  52. %%   Grave accent  \`     Left brace    \{     Vertical bar  \|
  53. %%   Right brace   \}     Tilde         \~}
  54. %\iffalse    This is a METACOMMENT
  55. %           Everything up to the next `\ fi' (without a blank) will
  56. %           be ignored.  This is necessary because `%' may no longer
  57. %           be a comment mark when this file is read in.
  58. %           
  59. % Style-option `doc' to use with LaTeX v2.09
  60. %% Copyright (C) 1989-1992 Frank Mittelbach, all rights reserved.
  61. % Version:     Date:     Changes:
  62. %  1.0a        5.5.88    This is nothing but a collection of tests and
  63. %                        hacks. It is certainly going to be greatly
  64. %                        changed.
  65. %                        Better not to use it!
  66. %  1.1a        13.5.88   \theindex and \endtheindex redefined.
  67. %  1.1b        15.5.88   \bslash redefined.
  68. %                        \verbatim changed so that `%'s will be ignored.
  69. %  1.1c        19.5.88   Partly documented and \@temp... in
  70. %                        \theindex replaced by private commands.
  71. %                        Moreover, \pageshrink incorporated in the
  72. %                        computation of the amount of free space on the
  73. %                        page.
  74. %  1.1d        3.6.88    Something goes wrong during the computation of
  75. %                        \pageshrink, therefore a bit of empty space is
  76. %                        inserted by
  77. %                        hand, and some tracing information introduced.
  78. %                        It can't stay like that!!
  79. %  1.2a        23.9.88   Documentation of the macros in DOC-format,
  80. %                        i.e. so that this file can document itself.
  81. %  1.2b        7.10.88   Change of the index environment.
  82. %  1.2c        10.10.88  Further Documentation.
  83. %  1.2d        19.10.88  \the before \catcode eliminated. (thanks P.
  84. %                        Breitenlohner)
  85. %  1.3a        24.10.88  Scanning of macro names via \scanmacro
  86. %                        introduced to produce index entries.
  87. %  1.3b         16.1.89  Scanning of macro names via \scanmacro
  88. %                        improved.
  89. %                        At present only suitable for the makeindex
  90. %                        program
  91. %                        in conjunction with a special style file.
  92. %                        Macro environment in `macro' environment
  93. %                        renamed.
  94. %  1.3c         30.1.89  Index environment removed. Will be developed in
  95. %                        other style file.
  96. %  1.4a         7.2.89   \SpecialEscapechar added (may change its name).
  97. %  1.4b         7.3.89   \SpecialEscapechar reimplemented.
  98. %  1.4c         9.3.89   \parts of \short@macro reimplemented because
  99. %                        of some bugs in the macros and the makeindex
  100. %                        program.
  101. %                        Old definition of \b@slash used for \bslash.
  102. %                        \b@slash removed.
  103. %  1.4d         10.3.89  English documentation added.
  104. %  1.4e         10.3.89  private names for private macros.
  105. %                        \makespecialletters renamed to
  106. %                        \MakePrivateLetters
  107. %  1.4f         12.3.89  \short@macro changed (again)
  108. %                        documentation update.
  109. %  1.4g         13.3.89  \DoNotIndex macros changed.
  110. %  1.4h         13.3.89  \DoNotIndex macros changed to version with
  111. %                        \@elt
  112. %  1.4i         15.3.89  documentation update
  113. %  1.4j         15.3.89  \printindex inserted
  114. %  1.4k         21.3.89  documentation update
  115. %                        \PrintDescribe... and \Describe... added
  116. %                        macro env. + \SpecialIndex changed to accept \
  117. %  1.4l         29.3.89  macro env. changed once more (\macro@ added) to
  118. %                        correct bug introduced in v1.4k
  119. %                        \SpecialUsageIndex and \SpecialEnvIndex added.
  120. %  1.4m          3.4.89  \OnlyDescription added, \MakePrivateLetters
  121. %                        changed
  122. %  1.4n         10.4.89  \MakePrivateLetters changed back to
  123. %                        \makeatletter.
  124. %                        \ifnot@excluded changed to allow other things
  125. %                        than
  126. %                        macro names in the exclude list (e.g. \abc*)
  127. %  1.4o         14.4.89  Documentation update (Brian's correction)
  128. %                        \EnableCrossrefs changed to disable
  129. %                        \DisableCrossrefs
  130. %  1.4p         15.4.89  Documentation update \Finale added,
  131. %                        some changes to index.tex 
  132. %  1.4q         19.4.89  Documentation update \verbatim changed (RmS)
  133. %                        twocolumns env. added index.tex changed.
  134. %  1.4r         22.4.89  Changed \macro@ to support \par and
  135. %                        conditionals (might be wrong.)
  136. %  1.4s         23.4.89  Getting nearer to the `final' version.
  137. %                        \@sphack ...
  138. %                        placed in several macros. Documentation update.
  139. %                        Tried a \changes macro (somewhere in the middle
  140. %                        of this file by using \glossary (might work!)
  141. %  1.4t         24.4.89  Should change to 1.5? Index now uses multicols
  142. %                        added \c@IndexColumns. Other changes forgotten.
  143. %                        Some macro names renamed.
  144. %  1.5a         26.4.89  Finally 1.5:  changes to \makelabel in macro
  145. %                        env.
  146. %  1.5b and higher...    are documented with the (undocumented) \changes
  147. %                        feature.
  148. %  \changes{v1.5f}{89/4/29}{Thanks to Brian who documented the
  149. %                          {\tt\bslash changes} macro feature.}
  150. %  \changes{v1.5g}{89/5/07}{MacroTopsep now called MacrocodeTopsep and
  151. %                          new MacroTopsep added}
  152. %  \changes{v1.5h}{89/05/17}{All lines shortened to <72 characters}
  153. %  \changes{v1.5j}{89/06/09}{Corrections by Ron Whitney added}
  154. %  \changes{v1.5q}{89/11/03}{`\ldots{}Listing macros renamed to
  155. %                         `\ldots{}Input. Suggested by R. Wonneberger}
  156. %  \changes{v1.5W}{90/02/05}{Counter codelineno renamed to CodelineNo}
  157. %                        
  158. % \hyphenation{make-index}
  159. % \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
  160. % \DoNotIndex{\@flushglue,\@gobble,\@input}
  161. % \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
  162. % \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
  163. % \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
  164. % \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
  165. % \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
  166. % \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
  167. % \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
  168. % \DoNotIndex{\cal,\csname,\def,\documentstyle,\dospecials,\edef}
  169. % \DoNotIndex{\egroup}
  170. % \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
  171. % \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
  172. % \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
  173. % \DoNotIndex{\ifcase}
  174. % \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
  175. % \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
  176. % \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
  177. % \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
  178. % \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
  179. % \DoNotIndex{\strutbox}
  180. % \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
  181. % \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
  182. % \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
  183. % \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
  184. % \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
  185. % \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
  186. % \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
  187. % \DoNotIndex{\nopagebreak}
  188. % \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
  189. % \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
  190. % \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
  191. % \DoNotIndex{\[,\{,\},\]}
  192. % \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
  193. % \DoNotIndex{\baselineskip,\begin,\tw@}
  194. % \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
  195. % \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
  196. % \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
  197. % \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
  198. % \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
  199. % \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
  200. % \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
  201. % \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
  202. % \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
  203. % \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
  204. % \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
  205. % \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
  206. % \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
  207. % \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
  208. % \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
  209. % \DoNotIndex{\bfdefault}
  210. % \MakeShortVerb{\"}
  211. % \setcounter{StandardModuleDepth}{1}
  212. % {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print
  213. % \gdef\dimenvalue#1pt{$#1$pt}}  ^^A a register value with a - sign
  214. % \makeatletter  ^^A hack so that this can be printed without multicols
  215. % \newif \ifmulticols
  216. % \ifhave@multicol \multicolstrue \fi
  217. % \makeatother
  218. % \title{The {\tt doc}--Option\thanks{%
  219. %    This file has version number \fileversion{} dated \filedate{}.
  220. %    The documentation was last revised on \docdate.
  221. %       }}
  222. % \author{Frank Mittelbach\thanks{Further commentary added at Royal
  223. %        Military College of Science by B. Hamilton Kelly; English
  224. %        translation of parts of the original German commentary
  225. %        provided by Andrew Mills; fairly substantial additions,
  226. %        particularly from {\tt newdoc},  and
  227. %        documentation of post-v1.5q features added at v1.7a by Dave
  228. %        Love (SERC Daresbury Lab).}\\
  229. %         Gutenberg Universit\"at Mainz}
  230. % \maketitle
  231. % \begin{abstract}
  232. %    This style option contains the definitions that are necessary to
  233. %    format the documentation of style files.  The style file was
  234. %    developed in Mainz in cooperation with the Royal Military College
  235. %    of Science.  This is an update which documents various changes
  236. %    and new features in {\sf doc} and integrates the features of {\sf
  237. %    newdoc}. 
  238. % \end{abstract}
  239. % \ifmulticols
  240. % \addtocontents{toc}{\protect\begin{multicols}{2}}
  241. % \fi
  242. % {\parskip 0pt                ^^A We have to reset \parskip
  243. %                              ^^A (bug in \LaTeX)
  244. % \tableofcontents
  245. % \changes{v1.7a}{92/02/25}{Miscellaneous small changes to the text}
  246. % \ifmulticols
  247. % \begin{multicols}{2}[\section*{Preface to version 1.7}]
  248. % \else \section*{Preface to version 1.7} \fi
  249. % This version of {\tt doc.doc} documents changes which have occurred
  250. % since the last published version \cite{art:doc} but which have been
  251. % present in distributed versions of {\tt doc.sty} for some time.  It
  252. % also integrates the (undocumented) features of the distributed {\tt
  253. % newdoc.sty}. 
  254. % The following changes and additions have been made to the user
  255. % interface since the published version~\cite{art:doc}.  See
  256. % \S\ref{sec:interface} for more details. 
  257. % \begin{description}
  258. % \item[Driver mechanism] "\DocInput" is now used in the driver file
  259. % to input possibly multiple independent {\tt doc} files and {\tt doc}
  260. % no longer has to be the last style option.  "\IndexListing" is
  261. % replaced by "\IndexInput";
  262. % \item[Indexing] is controlled by "\PageIndex" and
  263. % "\CodelineIndex", one of which must be specified to produce an
  264. % index---there is no longer a "\makeindex" in the default
  265. % "\DocstyleParms";
  266. % \item[The {\tt macro} environment] now takes as argument the macro
  267. % name {\em with\/} the backslash;
  268. % \item[Verbatim text] Newlines are now forbidden inside "\verb" and
  269. % commands "\MakeShortVerb" and "\DeleteShortVerb" are provided for
  270. % verbatim shorthand;
  271. % \item[{\tt \bslash par}] can now be used in "\DoNotIndex";
  272. % \item[Checksum/character table support] for ensuring the
  273. % integrity of distributions is added;
  274. % \item[{\tt \bslash printindex}] becomes "\PrintIndex";
  275. % \item[{\tt multicol.sty}] is no longer necessary to use {\tt doc} or
  276. % print the documentation (although it is recommended);
  277. % \item[`Docstrip' modules] are recognised and formatted specially.
  278. % \end{description}
  279. % As well as adding some completely new stuff,
  280. % the opportunity has been taken to add some commentary to the code
  281. % formerly in {\tt newdoc.sty} and that added after version 1.5k of
  282. % {\tt doc.sty}.  Since (as noted in the sections concerned) this
  283. % commentary wasn't written by Frank Mittelbach but the code was, it is
  284. % probably {\em not\/} true in this case that ``if the code and
  285. % comments disagree both are probably wrong''!
  286. % \subsection*{Bugs}
  287. % There are some known bugs in this version:
  288. % \begin{itemize}
  289. % \item The `General changes' glossary entry would come out after
  290. %    macro names with a leading "!" and possibly a leading \verb+"+;
  291. % \item If you have an old version of {\sf makeindex} long "\changes"
  292. %    entries will come out strangely and you may find the section
  293. %    header amalgamated with the first changes entry.  Try to get an
  294. %    up-to-date one (see p.~\pageref{makeindex:version});
  295. % \item Because the accompanying {\sf makeindex} style files support
  296. %    the inconsistent attribute specifications of older and newer
  297. %    versions {\sf makeindex} always complains about three `unknown
  298. %    specifier's when sorting the index and changes entries.
  299. % \item If "\MakeShortVerb" and "\DeleteShortVerb" are used with
  300. %    single character arguments, e.g., "{|}" instead of "{\|}" chaos
  301. %    may happen.
  302. % \end{itemize}
  303. % (Some `features' are documented below.)
  304. % \subsection*{Wish list}
  305. % \begin{itemize}
  306. % \item Hooks to allow "\DescribeMacro" and "\DescribeEnv" to write
  307. % out to a special file information about the style's `exported'
  308. % definitions which they describe.  This could subsequently be
  309. % included in the {\tt docstrip}ped {\tt .sty} file in a suitable form
  310. % for use by smart editors in command completion, spelling checking
  311. % etc., based on the style options of a document.  This would need
  312. % agreement on a `suitable form'.
  313. % \item Indexing of the modules used in {\tt docstrip}'s "%<"
  314. % directives.  I'm not sure how to index directives containing
  315. % module combinations;
  316. % \item Writing out bibliographic information about the style;
  317. % \item Allow turning off use of the special font for, say, the next
  318. % guarded block.
  319. % \end{itemize}
  320. % \ifmulticols
  321. % \end{multicols}
  322. % \begin{multicols}{2}[\medskip \rule{\textwidth}{.3pt}
  323. %                      \section{Introduction}]
  324. % \else
  325. % \section{Introduction}
  326. % \fi
  327. % The \TeX{} macros which are described here allow definitions and
  328. % documentation to be held in one and the same file.  This has the
  329. % advantage that normally very complicated instructions are made
  330. % simpler to understand by comments inside the definition. In addition
  331. % to this, updates are easier and only one source file needs to be
  332. % changed.  On the other hand, because of this, the style files are
  333. % considerably longer: thus \TeX{} takes longer to load them.  If this
  334. % is a problem, there is an easy remedy: one needs only to run the
  335. % {\tt docstrip.tex} program that removes nearly all lines that begin
  336. % with a
  337. % percent sign.
  338. % The idea of integrated documentation was born with the development
  339. % of the \TeX{} program; it was crystallized in Pascal with the \Web{}
  340. % system.  The advantages of this method are plain to see (it's easy
  341. % to make comparisons \cite{art:Knuthliterat}).  Since this
  342. % development, systems similar to \Web{} have been developed for other
  343. % programming languages. But for one of the most complicated
  344. % programming languages (\TeX) the documentation has however been
  345. % neglected.  The \TeX{} world seems to be divided between:---
  346. % \begin{itemize} \item a couple of ``wizards'', who produce many
  347. % lines of completely unreadable code ``off the cuff'', and \item many
  348. % users who are amazed that it works just how they want it to do.  Or
  349. % rather, who despair that certain macros refuse to do what is
  350. % expected of them.\end{itemize}
  351. % I do not think that the \Web{} system is {\em the\/} reference work;
  352. % on the contrary, it is a prototype which suffices for the
  353. % development of programs within the \TeX{} world.  It is sufficient,
  354. % but not totally sufficient.\footnote{I know that this will be seen
  355. % differently by a few people, but this product should not be seen as
  356. % the finished product, at least as far as applications concerning
  357. % \TeX{} are concerned.  The long-standing debate over `multiple
  358. % change files' shows this well.} As a result of \Web, new programming
  359. % perspectives have been demonstrated; unfortunately, though, they
  360. % haven't been developed further for other programming languages.
  361. % The method of documentation of \TeX{} macros which I have introduced
  362. % here should also only be taken as a first sketch.  It is designed
  363. % explicitly to run under \LaTeX{} alone.  Not because I was of the
  364. % opinion that this was the best starting point, but because from this
  365. % starting point it was the quickest to develop.\footnote{This
  366. % argument is a bad one, however, it is all too often trotted out.} As
  367. % a result of this design decision, I had to move away from the
  368. % concept of modularization; this was certainly a step backward.
  369. % I would be happy if this article could spark off discussion over
  370. % \TeX\ documentation.  I can only advise anyone who thinks that they
  371. % can cope without documentation to ``Stop Time'' until he or she
  372. % completely understands the \AmSTeX{} source code.
  373. % \subsection{Using the {\sf doc} style option}
  374. % Just like any other option, invoke it by including it amongst the
  375. % style options in the optional parameter list for the
  376. % \verb+\documentstyle+ command.  {\sf Doc}'s use of
  377. % \verb+\reversemarginpars+ may make it incompatible with some style
  378. % options.
  379. % \changes{v1.7a}{92/02/25}{Altered usage info}
  380. % \ifmulticols\end{multicols}\fi
  381. % \section{The User Interface}\label{sec:interface}
  382. % \subsection{The driver file}
  383. % If one is going to document a set of macros with the {\tt doc}
  384. % option one has to prepare a special driver file which produces the
  385. % formatted document. This driver file has the following
  386. % characteristics:
  387. % \noindent \verb+\documentstyle[+\meta{options}]^^A
  388. %           \verb+{+\meta{document-style}\verb+}+\\[3pt]
  389. % \hspace*{10pt}\meta{preamble}\\[3pt]
  390. % \verb+\begin{document}+\\[3pt]
  391. % \hspace*{10pt}\meta{special input commands}\\[3pt]
  392. % \verb+\end{document}+
  393. % The list of \meta{options} must contain the {\tt doc} option but it
  394. % is not necessary any longer to put this option on the end of the
  395. % list.
  396. % The \meta{document-style} might be any document style, I normally
  397. % use {\tt article}.
  398. % In the \meta{preamble} one should place declarations which
  399. % manipulate the behavior of the {\tt doc} option like
  400. % \verb+\DisableCrossrefs+ or \verb+\OnlyDescription+.
  401. % \DescribeMacro\DocInput \DescribeMacro\IndexInput
  402. % Finally the \meta{special input commands} part should contain one or
  403. % more \verb+\DocInput+\meta{file name} and/or
  404. % \verb+\IndexInput+\meta{file name} commands.  The
  405. % \verb+\DocInput+ command is used for files prepared for the {\tt
  406. % doc} option whereas \verb+\IndexInput+ can be used for all kinds of
  407. % macro files.  See page \pageref{..Input} for more details of
  408. % "\IndexInput".  Multiple "\DocInput"s can be used with a
  409. % number of included files which are each self-contained
  410. % self-documenting styles---for instance, each containing
  411. % "\maketitle". 
  412. % As an example, the driver file for the {\tt doc} option itself is
  413. % derived from the following text.  This is meant to be extracted by
  414. % the {\tt docstrip} program which will remove the leading "<+driver>"
  415. % indicating the `module'; the line numbers are added by {\tt
  416. % doc}'s formatting.
  417. % \changes{v1.7a}{92/03/06}{Added docstrip-derivable driver file as
  418. %                           example.}
  419. % \changes{v1.7c}{92/04/01}{Expurgated ltugboat.sty from driver.}
  420. %    \begin{macrocode}
  421. %<+driver>\documentstyle[doc]{article}
  422. %<+driver>% dimensions from ltugboat.sty:
  423. %<+driver>\setlength\textwidth{31pc} \setlength\textheight{54pc}
  424. %<+driver>\setlength{\parindent}{0pt} 
  425. %<+driver>\setlength{\parskip}{2pt plus 1pt minus 1pt}
  426. %<+driver>\setlength{\oddsidemargin}{8pc} 
  427. %<+driver>\setlength{\marginparwidth}{8pc}
  428. %<+driver>\setlength{\topmargin}{-2.5pc} 
  429. %<+driver>\setlength{\headsep}{20pt}
  430. %<+driver>\setlength{\columnsep}{1.5pc} 
  431. %<+driver>\setlength{\columnwidth}{18.75pc}
  432. %<+driver>\EnableCrossrefs         
  433. %<+driver>%\DisableCrossrefs % Say \DisableCrossrefs if index is ready
  434. %<+driver>\RecordChanges                  % Gather update information
  435. %<+driver>\CodelineIndex                  % Index code by line number
  436. %<+driver>%\OnlyDescription  % comment out for implementation details
  437. %<+driver>%\OldMakeindex     % use if your MakeIndex is pre-v2.9
  438. %<+driver>\begin{document}
  439. %<+driver>   \DocInput{doc.doc}
  440. %<+driver>\end{document}
  441. %    \end{macrocode}
  442. %^^A As an example this is the driver file for the {\tt doc} option
  443. %^^A itself: 
  444. %^^A\begin{verbatim}
  445. %^^A\documentstyle[ltugboat,doc]{article}
  446. %^^A %  \DisableCrossrefs     % Say \DisableCrossrefs if the index
  447. %^^A                          % is ready.
  448. %^^A    \RecordChanges        % Gather update-information
  449. %^^A %  \OnlyDescription      % Remove the comment char if you only want
  450. %^^A                          % the description
  451. %^^A\SelfDocumenting          % Tugbot style macro (for doc)
  452. %^^A\begin{document}
  453. %^^A   \DocInput{doc.doc}
  454. %^^A\end{document}
  455. %^^A\end{verbatim}
  456. % \changes{v1.7a}{92/02/25}{Note on avoiding driver file}
  457. % \subsection{Avoiding using a driver file}
  458. % It is possible to dispense with a driver file at the expense of some
  459. % flexibility using the following trick.\footnote{Due to David
  460. % Carlisle, Manchester University.}  Before the documentation part of
  461. % the file starts, include (without leading "%"s!)\ something like
  462. % \begin{verbatim}
  463. %\ifcat a\noexpand @\let\next\relax\else\def\next{%
  464. %    \documentstyle[doc]{article}\MakePercentIgnore}\fi\next
  465. %\end{verbatim}
  466. % with any necessary extra style options included, of course.  Then
  467. % the file can either be used directly as a style file as normal or
  468. % have the documentation printed simply by using
  469. % "latex"~\meta{filename}.  You can also arrange to have this process
  470. % ask questions about whether to format only the usage section, for
  471. % instance. 
  472. % \subsection{General conventions}
  473. % A \TeX{} file prepared to be used with the `doc' style option
  474. % consists of `documentation parts' intermixed with `definition
  475. % parts'.
  476. % Every line of a `documentation part' starts with a percent sign
  477. % (\verb+%+) in column one.  It may contain arbitrary \TeX{} or
  478. % \LaTeX{} commands except that the character `\verb+%+' cannot be
  479. % used as a comment character.
  480. % \SortIndex{\string^\string^A}{\string\verb\verbatimchar
  481. % \string^\string^A\verbatimchar \encapchar usage} To allow user
  482. % comments, the \verb+^^A+ character is defined as a comment character
  483. % later on.  Such `metacomments' may be also be included simply by
  484. % surrounding them with "\iffalse" \ldots~"\fi".
  485. % All other parts of the file are called `definition parts'.  They
  486. % contain fractions of the macros described in the `documentation
  487. % parts'.
  488. % If the file is used to define new macros (e.g.\ as a style file in
  489. % the \verb+\documentstyle+ macro), the `documentation parts' are
  490. % bypassed at high speed and the macro definitions are pasted
  491. % together, even if they are split into several `definition parts'.
  492. % \DescribeEnv{macrocode}
  493. % On the other hand, if the documentation of these macros is to be
  494. % produced, the `definition parts' should be typeset verbatim. To
  495. % achieve this, these parts are surrounded by the {\sf macrocode}
  496. % environment.
  497. % More exactly: before a `definition part' there should be a line
  498. % containing\\
  499. % \hspace*{\MacroIndent}\verb*+%    \begin{macrocode}+\\
  500. % and after this part a line\\
  501. % \hspace*{\MacroIndent}\verb*+%    \end{macrocode}+\\
  502. % There must be {\em exactly\/} four spaces between the \verb+%+
  503. % and \verb+\end{macrocode}+ --- \TeX{} is looking for this string
  504. % and not for the macro while processing a `definition part'.
  505. % Inside a `definition part' all \TeX{} commands are allowed; even the
  506. % percent sign could be used to suppress unwanted spaces etc.
  507. % \DescribeEnv{macrocode*}
  508. % Instead of the {\sf macrocode} environment one can also use the {\sf
  509. % macrocode$*$} environment which produces the same results except
  510. % that spaces are printed as \nopagebreak\verb*+ + characters.
  511. % \subsection{Describing the usage of new macros}
  512. % \DescribeMacro\DescribeMacro
  513. % When you describe a new macro you may use \verb+\DescribeMacro+ to
  514. % indicate that at this point the usage of a specific macro is
  515. % explained. It takes one argument which will be printed in the margin
  516. % and also produces a special index entry.  For example, I used
  517. % \verb+\DescribeMacro{\DescribeMacro}+ to make clear that this is the
  518. % point where the usage of \verb+\DescribeMacro+ is explained.
  519. % \DescribeMacro\DescribeEnv
  520. % An analogous macro \verb+\DescribeEnv+ should be used to indicate
  521. % that a \LaTeX{} environment is explained. It will produce a somewhat
  522. % different index entry. Below I used \verb+\DescribeEnv{verbatim}+.
  523. % \DescribeEnv{verbatim}
  524. % It is often a good idea to include examples of the usage of new macros
  525. % in the text. Because of the \verb+%+ sign in the first column of every
  526. % row, the {\sf verbatim} environment is slightly altered to suppress
  527. % those
  528. % characters.\footnote{These macros were written by Rainer
  529. %                      Sch\"opf~\cite{art:verbatim}. He also
  530. %                      provided a new {\sf verbatim} environment which
  531. %                      can be used inside of other macros.}
  532. % \DescribeEnv{verbatim*}
  533. % The {\sf verbatim$*$} environment is changed in the same way.
  534. % \changes{v1.7a}{92/02/26}{Documented `verb change.}
  535. % \DescribeMacro\verb
  536. % The "\verb" command is re-implemented to give an error report if a
  537. % newline appears in its argument. 
  538. % The {\sf verbatim} and {\sf verbatim$*$} environments set text in
  539. % the style defined by "\MacroFont"~(\S\ref{sec:macrofont}).
  540. % \subsection{Describing the definition of new macros}
  541. % \DescribeEnv{macro}
  542. % To describe the definition of a new macro we use the {\sf macro}
  543. % environment. It has one argument: the name of the new
  544. % macro.\footnote{This is a change to the style design I described in
  545. %                ^^A \TUB ^^A removed in case ltugboat.sty not used
  546. %                {\sl TUGboat\/}\ 10\#1 (Jan.~89). We finally decided
  547. %                that it would 
  548. %                be better to use the macro name {\em with\/} the
  549. %                backslash as an argument.}
  550. % This argument is also used to print the name in the margin and to
  551. % produce an index entry.
  552. % Actually the index entries for usage and definition are different to
  553. % allow an easy reference.
  554. % This environment might be nested. In this case the
  555. % labels in the margin are placed under each other.
  556. % \changes{v1.7a}{92/02/26}{Note on need for some text in macro env.}
  557. % There should be some text---even  if it's just an empty
  558. % "\mbox{}"---in this environment before "\begin{macrocode}" or the
  559. % marginal label won't print in the right place. 
  560. % \DescribeMacro\MacrocodeTopsep
  561. % \DescribeMacro\MacroTopsep
  562. % There also exist four style parameters: \verb+\MacrocodeTopsep+ and
  563. % \verb+\MacroTopsep+ are used to control the vertical spacing above
  564. % and below the {\sf macrocode} and the {\sf macro}
  565. % \DescribeMacro\MacroIndent
  566. % environment, \verb+\MacroIndent+ is used to indent the lines of code
  567. % and
  568. % \DescribeMacro\MacroFont \label{sec:macrofont}
  569. % \verb+\MacroFont+ holds the font and a possible size change command
  570. % for the code lines, the "verbatim"["*"] environment and the macro
  571. % names printed in the margin.  If you want
  572. % to change their default values in a 
  573. % style file (like {\tt ltugboat.sty}) use the \verb+\DocstyleParms+
  574. % command described below.
  575. % \subsection{Formatting the margins}
  576. % \DescribeMacro\PrintDescribeMacro
  577. % \DescribeMacro\PrintDescribeEnv
  578. % \DescribeMacro\PrintMacroName
  579. % As mentioned earlier, some macros and the {\sf macro} environment
  580. % print their arguments in the margin. This is actually done by three
  581. % macros which are user
  582. % definable.\footnote{You may place the changed definitions in a
  583. %                     separate style
  584. %                     file or at the beginning of the documentation
  585. %                     file.
  586. %                     For example, if you don't like any names in the
  587. %                     margin
  588. %                     but want a fine index you can simply
  589. %                     {\tt \bslash let}
  590. %                     these macros equal {\tt \bslash @gobble}.
  591. %                     The doc style option won't redefine any existing
  592. %                     definitions of these macros.}
  593. % They are named \verb+\PrintDescribeMacro+, \verb+\PrintDescribeEnv+
  594. % and \verb+\PrintMacroName+ (called by the {\sf macro} environment).
  595. % \subsection{Using a special escape character}
  596. % \DescribeMacro\SpecialEscapechar
  597. % If one defines complicated macros it is sometimes necessary to
  598. % introduce a new escape character because the `\verb+\+' has got a
  599. % special \verb+\catcode+. In this case one can use
  600. % \verb+\SpecialEscapechar+ to indicate which character is actually
  601. % used to play the r\^ole of the `\verb+\+'. A scheme like this is
  602. % needed because the {\sf macrocode} environment and its counterpart
  603. % {\sf macrocode$*$} produce an index entry for every occurrence of a
  604. % macro name. They would be very confused if you didn't tell them that
  605. % you'd changed \verb+\catcode+$\,$s.  The argument to
  606. % \verb+\SpecialEscapechar+ is a single-letter control sequence, that
  607. % is, one has to use \verb+\|+ for example to denote that `\verb+|+'
  608. % is used as an escape character. \verb+\SpecialEscapechar+ only
  609. % changes the behavior of the next {\sf macrocode} or {\sf
  610. % macrocode$*$} environment.
  611. %  The actual index entries created will all be printed with \verb+\+
  612. % rather than \verb+|+, but this probably reflects their usage, if not
  613. % their definition, and anyway must be preferable to not having any
  614. % entry at all.  The entries {\em could\/} be formatted appropriately,
  615. % but the effort is hardly worth it, and the resulting index might be
  616. % more confusing (it would certainly be longer!).
  617. % \subsection{Cross-referencing all macros used}
  618. % \DescribeMacro\DisableCrossrefs
  619. % \DescribeMacro\EnableCrossrefs
  620. % As already mentioned, every new macro name used within a {\sf
  621. % macrocode} or {\sf macrocode$*$} environment will produce an index
  622. % entry. In this way one can easily find out where a specific macro is
  623. % used.  Since \TeX{} is considerably slower when it has to produce
  624. % such a bulk of index entries one can turn off this feature by using
  625. % \verb+\DisableCrossrefs+ in the driver file. To turn it on again
  626. % just use
  627. % \verb+\EnableCrossrefs+.\footnote{Actually,
  628. %          {\tt\bslash EnableCrossrefs}
  629. %          changes things more drastically; any following
  630. %          {\tt\bslash DisableCrossrefs}
  631. %          which might be present in the source will be ignored.}
  632. % \DescribeMacro\DoNotIndex
  633. % But also finer control is provided. The \verb+\DoNotIndex+ macro
  634. % takes a list of macro names separated by commas. Those names won't
  635. % show up in the index. You might use several \verb+\DoNotIndex+
  636. % commands: their lists will be concatenated.  In this article I used
  637. % \verb+\DoNotIndex+ for
  638. % all macros which are already defined in \LaTeX.
  639. % All three above declarations are local to the current group.
  640. % Production (or not) of the index (via the "\makeindex" commend) is
  641. % controlled by using or omitting the following declarations in the
  642. % driver file preamble; if neither is used, no index is produced.
  643. % \DescribeMacro\PageIndex Using "\PageIndex" makes all index
  644. % entries refer to their page number; with
  645. % \DescribeMacro\CodelineIndex "\CodelineIndex", index entries
  646. % produced by "\DescribeMacro" and "\DescribeEnv" refer to page number
  647. % but those produced by the {\sf macro} environment refer to the
  648. % code lines, which will be numbered automatically.\footnote{The line
  649. % number is actually that of the first line of the first {\sf
  650. % macrocode} environment in the {\sf macro} environment.}
  651. % \DescribeMacro\theCodelineNo
  652. % The style of this numbering can be controlled by defining the macro
  653. % "\theCodelineNo".  Its default definition is to use scriptsize
  654. % arabic numerals; a user-supplied definition won't be overwritten.
  655. % \subsection{Producing the actual index entries}
  656. % Several of the aforementioned macros will produce some sort of index
  657. % entries. These entries have to be sorted by an external
  658. % program---the current implementation assumes that the {\sf
  659. % makeindex} program by Chen~\cite{art:Chen} is used.
  660. % But this isn't built in: one has only to redefine some of the
  661. % following macros to be able to use any other index program.  All
  662. % macros which are installation 
  663. % dependent are defined in such a way that they won't overwrite a
  664. % previous definition. Therefore it is safe to put the changed
  665. % versions in a style file which might be read in before the doc style
  666. % option.
  667. %  To allow the user to change the specific characters recognized by
  668. %  his or her index program all characters which have special meaning
  669. %  in the {\sf makeindex} program are given symbolic
  670. %  names.\footnote{I don't know if there exists a program which needs
  671. %                  more command characters, but I hope not.}
  672. % However, all characters used should be of \verb+\catcode+ other than
  673. % `letter' (11).
  674. % \DescribeMacro{\actualchar}
  675. % The \verb+\actualchar+ is used to separate the `key' and the actual
  676. % index entry.
  677. % \DescribeMacro{\quotechar}
  678. % The \verb+\quotechar+ is used before a special index program
  679. % character to suppress its special meaning.
  680. % \DescribeMacro{\encapchar}
  681. %  The \verb+\encapchar+ separates the indexing information from a
  682. % letter string which {\sf makeindex} uses as a \TeX{} command to
  683. % format the page number associated with a special entry.  It is used
  684. % in this style to apply the \verb+\main+ and the \verb+\usage+
  685. % commands.
  686. % \DescribeMacro{\levelchar}
  687. %  Additionally \verb+\levelchar+ is used to separate `item',
  688. % `subitem' and `subsubitem' entries.
  689. % It is a good idea to stick to these symbolic names even if you know
  690. % which index program is used. In this way your files will be
  691. % portable.
  692. % \DescribeMacro\SpecialMainIndex
  693. % To produce a main index entry for a macro the
  694. % \verb+\SpecialMainIndex+ macro\footnote{This macro is called by the
  695. % {\sf macro} environment.} may be used.  It is called `special'
  696. % because it has to print its argument verbatim.
  697. % \DescribeMacro\SpecialIndex
  698. % If you want a normal index entry for a macro name
  699. % \verb+\SpecialIndex+ might be used.\footnote{This macro is called
  700. % within the {\sf macrocode} environment when encountering a macro
  701. % name.}
  702. % \DescribeMacro\SpecialUsageIndex
  703. % \DescribeMacro\SpecialEnvIndex
  704. % To index the usage of a macro or an environment
  705. % \verb+\SpecialUsageIndex+ and \verb+\SpecialEnvIndex+ may be used.
  706. % \DescribeMacro\SortIndex
  707. % Additionally a \verb+\SortIndex+ command is provided.  It takes two
  708. % arguments---the sort key and the actual index entry.
  709. % All these macros are normally used by other macros; you will need
  710. % them only in an emergency.
  711. % \DescribeMacro\verbatimchar
  712. % But there is one characteristic worth mentioning: all macro names in
  713. % the index are typeset with the \verb+\verb*+ command. Therefore one
  714. % special character is needed to act as a delimiter for this command.
  715. % To allow a change in this respect, again this character is
  716. % referenced indirectly, by the macro \verb+\verbatimchar+. It expands
  717. % by default to \verb?+?  but if your code lines contain macros with
  718. % `{\tt +}' characters in their names (e.g.\ when you use \verb?\+?)
  719. % you will end up with an index entry containing \verb?\verb+\++?
  720. % which will be typeset as `\verb+\++' and not as `\verb?\+?'. In this
  721. % case you should redefine \verb+\verbatimchar+ globally or locally to
  722. % overcome this problem.
  723. % \DescribeMacro\*
  724. % We also provide a \verb+\*+ macro.  This is intended to be used for
  725. % index entries like
  726. % \begin{quote}
  727. %    index entries \\
  728. %    \hspace*{30pt} Special macros for \*
  729. % \end{quote}
  730. % Such an entry might be produced with the line:
  731. %\begin{verbatim}
  732. %   \index{index entries\levelchar Special macros for \*}
  733. %\end{verbatim}
  734. % \DescribeMacro\OldMakeindex
  735. % Versions of {\sf makeindex} prior to 2.9 had some bugs affecting
  736. % {\sf doc}.  One of these, 
  737. % pertaining to the "%" character doesn't have a work-around
  738. % appropriate for versions with and without the
  739. % bug.\label{makeindex:version}  If
  740. % you have an old version, invoke "\OldMakeindex" in a
  741. % style file or the driver file to prevent problems with index entries
  742. % such as "\%", although you'll probably normally want to turn off
  743. % indexing of "\%" anyway.  Try to get an up-to-date {\sf makeindex}
  744. % from one of the \TeX{} repositories.
  745. % \subsection{Setting the index entries}
  746. % \changes{v1.7a}{92/03/11}{Usage note on gind.ist.}
  747. % After the first formatting pass through the {\tt .doc} file you need
  748. % to sort the index entries written to the {\tt .idx} file using {\sf
  749. % makeindex} or your favourite alternative.  You need a suitable style
  750. % file for {\sf makeindex} (specified by the {\tt -s} switch).  A
  751. % suitable one is supplied with {\sf doc}, called {\tt gind.ist}.
  752. % \DescribeMacro\PrintIndex
  753. % To read in and print the sorted index, just put the
  754. % \verb+\PrintIndex+ command as the last (commented-out, and thus
  755. % executed during the documentation pass through the file) command
  756. % in your style file.  Precede it by any bibliography commands
  757. % necessary for your citations.
  758. % Alternatively, it may be more convenient to put all such calls
  759. % amongst the arguments of the \verb+\StopEventually+ macro, in
  760. % which case a \verb+\Finale+ command should appear at the end of
  761. % your file.
  762. % \DescribeEnv{theindex}
  763. % Contrary to standard \LaTeX, the index is typeset in three columns
  764. % by default. This is controlled by the \LaTeX{} counter `{\sf
  765. % IndexColumns}' and can therefore be changed with a
  766. % \verb+\setcounter+ declaration.  Additionally one doesn't want to
  767. % start a new page unnecessarily.  Therefore the {\sf theindex}
  768. % environment is redefined.
  769. % \DescribeMacro\IndexMin
  770. % When the {\sf theindex} environment starts it will measure how much
  771. % space is left on the current page. If this is more than
  772. % \verb+\IndexMin+ then the index will start on this page. Otherwise
  773. % \verb+\newpage+ is called.
  774. % Then a short introduction about the meaning of several index entries
  775. % is typeset (still in onecolumn mode). Afterwards the actual index
  776. % entries follow in multi-column mode.
  777. % \DescribeMacro\IndexPrologue
  778. % You can change this prologue with the help of the
  779. % \verb+\IndexPrologue+ macro. Actually the section heading is also
  780. % produced in this way, so you'd better write something like:
  781. % \begin{verbatim}
  782. %   \IndexPrologue{\section*{Index} The index entries underlined ...} 
  783. %\end{verbatim}
  784. % When the {\sf theindex} environment is finished the last page will
  785. % be reformatted to produce balanced columns. This improves the layout
  786. % and allows the next article to start on the same page.
  787. % \DescribeMacro\IndexParms
  788. % Formatting of the index columns (values for \verb+\columnssep+
  789. % etc.)\ is controlled by the \verb+\IndexParms+ macro. It assigns the
  790. % following values:
  791. % \SpecialUsageIndex{\parindent}\SpecialUsageIndex{\columnsep}^^A
  792. % \SpecialUsageIndex{\parskip}\SpecialUsageIndex{\rightskip}^^A
  793. % \SpecialUsageIndex{\mathsurround}\SpecialUsageIndex{\parfillskip}
  794. % \begin{center}
  795. %  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
  796. %  \verb+\parindent+    & \IndexParms \the\parindent    &
  797. %  \verb+\columnsep+    & \IndexParms \the\columnsep    \\
  798. %  \verb+\parskip+      & \IndexParms \the\parskip           &
  799. %  \verb+\rightskip+    & \IndexParms 
  800. %                         \expandafter\dimenvalue\the\rightskip  \\
  801. %  \verb+\mathsurround+ & \IndexParms \the\mathsurround  &
  802. %  \verb+\parfillskip+  & \IndexParms 
  803. %                         \expandafter\dimenvalue\the\parfillskip      
  804. %  \end{tabular}
  805. % \end{center}
  806. % \DescribeMacro{\@idxitem}
  807. % Additionally it defines \verb+\@idxitem+ (which will be used when an
  808. % \verb+\item+ command is encountered) and selects \verb+\small+ size.
  809. % If you want to change any of these values you have to define them
  810. % all.
  811. % \DescribeMacro\main
  812. % \DescribeMacro\usage
  813. % The page numbers for main index entries are encapsulated by the
  814. % \verb+\main+ macro (underlining its argument) and the numbers
  815. % denoting the description are encapsulated by the \verb+\usage+ macro
  816. % (which produces {\em italics}). As usual these commands are user
  817. % definable.
  818. % \subsection{Changing the default values of style parameters}
  819. % \DescribeMacro\DocstyleParms
  820. % If you want to overwrite some default settings made by the {\tt doc}
  821. % style, you can either put your declarations in the driver file (that
  822. % is after {\tt doc.sty} is read in) or use a separate style file for
  823. % doing this work. In the latter case you can define the macro
  824. % \verb+\DocstyleParms+ to contain all assignments.  This
  825. % indirect approach is necessary if your style file might be read
  826. % before the {\tt doc.sty}, when some of the registers are not
  827. % allocated.  Its default definition is null.
  828. % The doc style option currently assigns values to the following
  829. % registers:
  830. % \SpecialUsageIndex{\IndexMin}\SpecialUsageIndex{\MacrocodeTopsep}^^A
  831. % \SpecialUsageIndex{\MacroTopsep}^^A
  832. % \SpecialUsageIndex{\MacroIndent}\SpecialUsageIndex{\marginparpush}^^A
  833. % \SpecialUsageIndex{\marginparwidth}\SpecialUsageIndex{\tolerance}
  834. % \begin{center}
  835. %  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
  836. %  \verb+\IndexMin+      & \the\IndexMin    &
  837. %  \verb+\MacroTopsep+   & \the\MacroTopsep    \\
  838. %  \verb+\marginparwidth+& \the\marginparwidth  &
  839. %  \verb+\MacroIndent+   & \the\MacroIndent \\
  840. %  \verb+\marginparpush+ & \the\marginparpush    &
  841. %  \verb+\MacrocodeTopsep+   & \the\MacrocodeTopsep \\
  842. %  \verb+\tolerance+     & \the\tolerance  
  843. %  \end{tabular}
  844. % \end{center}
  845. % \subsection{Additional bells and whistles}
  846. % We provide macros for logos such as \Web, \AmSTeX, \BibTeX,
  847. % \SliTeX{} and \PlainTeX. Just type \verb+\Web+, \verb+\AmSTeX+,
  848. % \verb+\BibTeX+, \verb+\SliTeX+ or \verb+\PlainTeX+, respectively.
  849. % \LaTeX{} and \TeX{} are already defined in {\tt latex.tex}.
  850. % \DescribeMacro\meta
  851. % Another useful macro is \verb+\meta+ which has one argument and
  852. % produces something like \meta{dimen parameter}.
  853. % \DescribeMacro\OnlyDescription
  854. % \DescribeMacro\StopEventually
  855. % You can use the \verb+\OnlyDescription+ declaration in the driver
  856. % file to suppress the last part of your document (which presumably
  857. % exhibits the code). To make this work
  858. % you have to place the command \verb+\StopEventually+ at a suitable
  859. % point in your file.  This macro has one argument in which you put
  860. % all information you want to see printed if your document ends at
  861. % this point (for example a bibliography which is normally printed at
  862. % the very end). When the \verb+\OnlyDescription+ declaration is
  863. % missing the \verb+\StopEventually+
  864. % \DescribeMacro\Finale
  865. % macro saves its argument in a macro called \verb+\Finale+ which can
  866. % afterwards be used to get things back (usually at the very end).
  867. % Such a scheme makes changes in two places unnecessary.
  868. % Thus you can use this feature to produce a local guide for the
  869. % \TeX{} users which describes only the usage of macros (most of them
  870. % won't be interested in your definitions anyway).  For the same
  871. % reason the \verb+\maketitle+
  872. % \DescribeMacro\maketitle 
  873. % command is slightly changed to allow multiple titles in one
  874. % document.  So you can make one driver file reading in several
  875. % articles at once.
  876. % \DescribeMacro{\ps@titlepage}
  877. % To avoid an unwanted {\sf pagestyle} on the title page the
  878. % \verb+\maketitle+ command issues a \verb+\thispagestyle{titlepage}+
  879. % declaration which produces a {\sf plain} page if the {\sf titlepage}
  880. % page style is undefined.  This allows style files like {\sf
  881. % ltugboat.sty} to define their own page styles for title pages.
  882. % \DescribeMacro\IndexInput \label{..Input}
  883. % Last but not least I defined an \verb+\IndexInput+ macro which
  884. % takes a file name as an argument and produces a verbatim listing of
  885. % the file, indexing every command as it goes along.  This might be
  886. % handy, if you want to learn something about macros without enough
  887. % documentation.  I used this feature to cross-reference {\tt
  888. % latex.tex} getting a verbatim copy with about 15 pages
  889. % index.\footnote{It took quit a long time and the resulting {\tt .idx}
  890. %                file was longer than the {\tt .dvi} file.
  891. %                Actually too long to be handled by the {\sf makeindex}
  892. %                program directly (on our MicroVAX) but the final result
  893. %                was worth the trouble.}
  894. % \DescribeMacro\changes
  895. % To maintain a change history within the file, the \verb+\changes+
  896. % command may be placed amongst the description part of the changed
  897. % code.  It takes three arguments, thus:
  898. % \begin{quote}
  899. % \verb+\changes{+\meta{version}\verb+}{+\meta{date}\verb+}{+^^A
  900. % \meta{text}\verb+}+
  901. % \end{quote}
  902. % The changes may be used to produce an auxiliary file (\LaTeX's
  903. % \verb+\glossary+ mechanism is used for this) which may be printed
  904. % after suitable formatting. The \verb+\changes+ macro encloses the
  905. % \meta{date} in parentheses and appends the \meta{text} to form the
  906. % printed entry in such a change history; because old
  907. % versions\footnote{Before 2.6.} of the {\sf makeindex} 
  908. % program limit such fields to 64 characters, care should be taken
  909. % not to exceed this limit when describing the change.  When
  910. % referring to macros in change descriptions it is conventional to use
  911. % "`"\meta{macroname} rather than attempting to format it properly and
  912. % using up valuable characters in the entry with old {\sf makeindex}
  913. % versions.
  914. % \changes{v1.7a}{92/02/26}{Description of `RecordChanges etc. added
  915. %                           to interface section.}
  916. % \DescribeMacro\RecordChanges
  917. % To cause the change information to be written out, include
  918. % "\RecordChanges" in the driver file.
  919. % \DescribeMacro\PrintChanges
  920. % To read in and print the sorted change history (in two columns),
  921. % just put the \verb+\PrintChanges+ command as the last
  922. % (commented-out, and thus executed during the documentation pass
  923. % through the file) command in your style file.  Alternatively, this
  924. % command may form one of the arguments of the \verb+\StopEventually+
  925. % command, although a change history is probably {\em not\/} required
  926. % if only the description is being printed.
  927. % The command assumes that {\sf makeindex} or some other program
  928. % has processed the {\tt.glo} file to generate a sorted {\tt.gls} file.
  929. % You need a special {\sf makeindex} style file; a suitable one is
  930. % supplied with {\sf doc}, called {\tt gglo.ist}.
  931. % \DescribeMacro\GlossaryMin \DescribeMacro\GlossaryPrologue
  932. % \DescribeMacro\GlossaryParms
  933. % The "\GlossaryMin", "\GlossaryPrologue" and  "\GlossaryParms" macros
  934. % are analagous to the "\Index"\ldots\ versions.  (The \LaTeX{}
  935. % `glossary' mechanism is used for the change entries.)
  936. % \label{sec:checksum}
  937. % \DescribeMacro\CharacterTable
  938. % \DescribeMacro\CheckSum 
  939. % To overcome some of the problems of sending files over the networks
  940. % we developed two macros which should detect corrupted files. If one
  941. % places the lines
  942. % \begin{verbatim}
  943. %%% \CharacterTable
  944. %%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
  945. %%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
  946. %%%   Digits        \0\1\2\3\4\5\6\7\8\9
  947. %%%   Exclamation   \!     Double quote  \"     Hash (number) \#
  948. %%%   Dollar        \$     Percent       \%     Ampersand     \&
  949. %%%   Acute accent  \'     Left paren    \(     Right paren   \)
  950. %%%   Asterisk      \*     Plus          \+     Comma         \,
  951. %%%   Minus         \-     Point         \.     Solidus       \/
  952. %%%   Colon         \:     Semicolon     \;     Less than     \<
  953. %%%   Equals        \=     Greater than  \>     Question mark \?
  954. %%%   Commercial at \@     Left bracket  \[     Backslash     \\
  955. %%%   Right bracket \]     Circumflex    \^     Underscore    \_
  956. %%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
  957. %%%   Right brace   \}     Tilde         \~}
  958. %\end{verbatim}
  959. % at the beginning of the file then character translation failures
  960. % will be detected, provided of course, that the used {\tt doc} option
  961. % has a correct default table.  The percent signs\footnote{There are
  962. % two percent signs in each line. This has the effect that these lines
  963. % are not removed by the {\tt docstrip.tex} program.} at the beginning
  964. % of the lines should be typed in, since only the {\tt doc} option
  965. % should look at this command.
  966. % Another problem of mailing files is possible truncation.  To
  967. % detect these sort of errors we provide a \verb+\CheckSum+ macro.
  968. % The check-sum of a file is simply the number of backslashes in the
  969. % code, i.e.\ all lines between the {\sf macrocode} environments.  But
  970. % don't be afraid: you don't have count the code-lines yourself; this
  971. % is done by the {\tt doc} style option for you.  You simply have to
  972. % use the \verb+\StopEventually+ (which starts looking for backslashes)
  973. % and the \verb+\Finale+ command.  The latter will inform you either
  974. % that your file has no check-sum (telling you the right number) or
  975. % that your number is incorrect (this time telling you both the
  976. % correct and the incorrect one).  Then you go to the top of your file
  977. % inserting the line
  978. % \begin{quote}
  979. %    \verb+%%   \CheckSum{+\meta{number}\verb+}+
  980. % \end{quote}
  981. % and that's all. If you precede it only with one percent then the
  982. % line will not show up in {\tt docstrip} versions of the file.
  983. % You should do so whenever you are using conditional code (see
  984. % {\tt docstrip} documentation) since then the check-sum will not
  985. % reflect the number of backslashes in the stripped of versions.
  986. % \DescribeMacro\bslash
  987. % From time to time, it is necessary to print a \verb+\+ without
  988. % being able to use the \verb+\verb+ command because the
  989. % \verb+\catcode+$\,$s of the symbols are already firmly
  990. % established.  In this instance we can use the command
  991. % \verb+\bslash+ presupposing, of course, that the actual font in
  992. % use at this point contains a `backslash' as a symbol.  Note that
  993. % this definition of \verb+\bslash+ is expandable; it inserts a
  994. % $"\"_{12}$.  This means that you have to \verb+\protect+
  995. % it if it is used in `moving arguments'.
  996. % \DescribeMacro\MakePrivateLetters
  997. % \changes{v1.7a}{92/02/26}{Documented `MakePrivateLetters in
  998. %                           interface section}^^A
  999. % If your macros "\catcode" anything other than "@" to `letter', you
  1000. % should redefine "\MakePrivateLetters" so that it also makes the
  1001. % relevant characters `letters' for the benefit of the indexing.  The
  1002. % default definition is just "\makeatletter".
  1003. % \DescribeMacro\MakeShortVerb \DescribeMacro\DeleteShortVerb
  1004. % It is awkward to have to type, say, "\verb+"\ldots"+" continually
  1005. % when quoting verbatim bits (like macro names) in the text, so an
  1006. % abbreviation mechanism is provided.  Pick a character
  1007. % \meta{c}---one which normally has catcode `other' unless you have
  1008. % very good reason not to---which
  1009. % you don't envisage using in the text, or not using often.  (I like
  1010. % \verb+"+, but you may prefer "|" if you have \verb+"+ active to do
  1011. % umlauts, for instance.)  Then if you say
  1012. % "\MakeShortVerb{\"\meta{c}"}" you can subsequently use
  1013. % \meta{c}\meta{text}\meta{c} as the equivalent of
  1014. % "\verb"\meta{c}\meta{text}\meta{c}.  Use
  1015. % "\DeleteShortVerb{\"\meta{c}"}" if you subsequently
  1016. % want \meta{c} to revert to its previous meaning---you can
  1017. % always turn it on again after the unusual section.  The `short verb'
  1018. % commands make global changes.  The abbreviated "\verb" may not
  1019. % appear in the argument of another command just like "\verb".
  1020. % However the `short verb' character may be used freely in the {\sf
  1021. % verbatim} and {\sf macrocode} environments without ill effect.
  1022. % "\DeleteShortVerb" is silently ignored if its argument does not
  1023. % currently represent a short verb character.  Both commands type a
  1024. % message to tell you the meaning of the character is being changed.
  1025. % \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules
  1026. % \DescribeMacro\Module \DescribeMacro\AltMacroFont
  1027. % The `module' directives of the {\sf docstrip} system
  1028. % \cite{art:docstrip} are normally 
  1029. % recognised and invoke special formatting.  This can be turned on and
  1030. % off in the {\tt .doc} file or the driver file using "\CheckModules"
  1031. % and "\DontCheckModules".  If checking for module directives is on
  1032. % (the default) then code in the scope of the directives is set as
  1033. % determined by the hook "\AltMacroFont", which gives {\small\tt\it
  1034. % small italic type\-writer\/} by default in the New Font
  1035. % Selection Scheme but just ordinary {\small\tt small type\-writer} in
  1036. % the old one, where a font such as italic typewriter can't be used
  1037. % portably (plug for NFSS); you will need to override
  1038. % this if you don't have the italic typewriter font available.
  1039. % Code is in such a scope if it's on a line beginning with "%<" or is
  1040. % between lines starting with "%<*"\meta{name list}">" and
  1041. % "%</"\meta{name list}">".  The directive is formatted by the macro
  1042. % "\Module" whose single argument is the text of the
  1043. % directive between, but not including, the angle brackets; this macro
  1044. % may be re-defined in the driver or style file and by default
  1045. % produces results like \Module{+foo|bar} with no following space.
  1046. % \DescribeMacro{StandardModuleDepth} Sometimes (as in this file) the
  1047. % whole code is surrounded by modules to produce several files from a
  1048. % single source. In this case it is clearly not appropriate to format
  1049. % all code lines in a special "\AltMacroFont". For this reason a
  1050. % counter "StandardModuleDepth" is provided which defines the level of
  1051. % module nesting which is still supposed to be formatted in
  1052. % "\MacroFont" rather then "\AltMacroFont". The default setting is
  1053. % "0", for this documentation it was set to
  1054. %\begin{verbatim}
  1055. %   \setcounter{StandardModuleDepth}{1}
  1056. %\end{verbatim}
  1057. % at the beginning of the file.
  1058. % \subsection{Basic usage summary}
  1059. % \changes{v1.7a}{92/03/11}{Added basic usage summary to spell it out.}
  1060. % To sum up, the basic structure of a {\tt .doc} file without any
  1061. % refinements is like this: 
  1062. % \begin{verse}\small
  1063. % "% "\meta{waffle}\ldots\\
  1064. % \quad\ldots \\
  1065. % "% \DescribeMacro{\fred}"\\
  1066. % "% "\meta{description of fred's use}\\
  1067. % \quad\ldots\\
  1068. % "% \StopEventually{"\meta{finale code}"}"\\
  1069. % \quad\ldots\\
  1070. % "% \begin{macro}{\fred}"\\
  1071. % "% "\meta{commentary on macro fred}\\
  1072. % \verb*+%    \begin{macrocode}+\\
  1073. % \meta{code for macro fred}\\
  1074. % \verb*+%    \end{macrocode}+\\
  1075. % "% \end{macro}"\\
  1076. % \quad\ldots\\
  1077. % "% \Finale \PrintIndex \PrintChanges"
  1078. % \end{verse}
  1079. % For examples of the use of most---if not all---of the features
  1080. % described above consult the {\tt doc.doc} source itself. 
  1081. % \subsection{Acknowledgements}
  1082. % I would like to thank all folks at Mainz and at the Royal Military
  1083. % College of Science for their help in this project. Especially Brian
  1084. % and Rainer who pushed everything with their suggestions, bug fixes,
  1085. % etc.
  1086. % A big thank you to David Love who brought the documentation
  1087. % up-to-date again, after I neglected this file for more than two
  1088. % years. This was most certainly a tough job as many features added to
  1089. % {\sf doc.doc} after its publication in {\sl TUGboat\/} have been never
  1090. % properly described. Beside this splendid work he kindly provided
  1091. % additional code (like ``docstrip'' module formatting) which I think
  1092. % every {\sf doc.doc} user will be grateful for.
  1093. % \StopEventually{
  1094. %  \begin{thebibliography}{1}
  1095. %    \bibitem{book:Buerger}  {\sc G. A. B\"urger}.
  1096. %      \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldz\"uge
  1097. %                und lustige Abenteuer des Freyherrn v.\ M\"unchhausen.
  1098. %      \newblock London, 1786 \& 1788.
  1099. %    \bibitem{art:Knuthliterat} {\sc D. E. Knuth}.
  1100. %      \newblock Literate Programming.
  1101. %      \newblock Computer Journal, Vol.~27, {\it pp}.~97--111, May 1984.
  1102. %    \bibitem{book:KnuthA} {\sc D. E. Knuth}.
  1103. %      \newblock Computers \& Typesetting (The \TeX book).
  1104. %      \newblock Addison-Wesley, Vol. A, 1986.
  1105. %    \bibitem{art:Chen} {\sc L. Lamport}.
  1106. %      \newblock MakeIndex: An Index Processor for \LaTeX.
  1107. %      \newblock 17 February 1987.
  1108. %      \newblock (Taken from the file {\tt makeindex.tex} provided with
  1109. %      the program source code.)
  1110. %    \bibitem{art:doc} {\sc Frank Mittelbach}.
  1111. %      \newblock The {\tt doc}-option.
  1112. %      \newblock {\sl TUGboat}, Vol.~10(2), {\it pp}.~245--273, July
  1113. %        1989.
  1114. %    \bibitem{art:docstrip} {\sc Frank Mittelbach, Denys Duchier and
  1115. %         Johannes Braams}. 
  1116. %      \newblock {\tt docstrip.doc} (to appear).
  1117. %      \newblock The file is part of the DOC package.
  1118. %    \bibitem{book:Raspe} {\sc R. E. Raspe} (*1737, \dag 1797).
  1119. %      \newblock Baron M\"unchhausens narrative of his marvellous
  1120. %                travels and campaigns in Russia.
  1121. %      \newblock Oxford, 1785.
  1122. %    \bibitem{art:verbatim} {\sc Rainer Sch\"opf}.
  1123. %      \newblock A New Implementation of \LaTeX's {\tt verbatim} and
  1124. %      {\tt verbatim*} Environments.
  1125. %      \newblock File {\tt verbatim.doc}, version 1.4i.
  1126. %  \end{thebibliography}
  1127. %  ^^A\PrintIndex
  1128. %  ^^A\PrintChanges
  1129. %  \ifmulticols
  1130. %  \addtocontents{toc}{\protect\end{multicols}}
  1131. %  \fi
  1132. % } ^^A end \StopEventually
  1133. % \section{The Description of Macros}
  1134. % Most of the following code is destined for {\tt doc.sty} after
  1135. % processing with {\tt docstrip} to include the module {\bf style}
  1136. % indicated here.  (All code in this file not appropriate to {\tt
  1137. % doc.sty} has to be included explicitly by docstrip so that this {\tt
  1138. % .doc} file can be used as directly as a style file rather than the
  1139. % stripped version.)  The usual font change for the
  1140. % conditionally-included lines between the \Module{*style} and
  1141. % \Module{/style} directives is suppressed since only the lines with
  1142. % an explicit directive are special in this file.
  1143. %    \begin{macrocode}
  1144. %<*style>
  1145. %    \end{macrocode}
  1146. % As always, we begin by identifying the latest version of this file
  1147. % on the VDU and in the {\sf log} file. But only if the macros are
  1148. % unknown to the system.  
  1149. % \changes{v1.5i}{89/06/07}{Avoid reading the file twice.}
  1150. %    \begin{macrocode}
  1151. \@ifundefined{macro@cnt}{}{\endinput} \typeout{Style-Option: `doc'
  1152. \fileversion \@spaces\space\space <\filedate> (FMi)} \typeout{English
  1153.    Documentation \@spaces\@spaces\space <\docdate> (DLo, FMi, RMCS)}
  1154. %    \end{macrocode}
  1155. % \DescribeMacro\fileversion
  1156. % \DescribeMacro\filedate
  1157. % \DescribeMacro\docdate
  1158. % As you can see I used macros like \verb+\fileversion+ to denote the
  1159. % version number and the date. They are defined at the very beginning
  1160. % of the style file (without a surrounding {\sf macrocode}
  1161. % environment), so I don't have to search for this place here when I
  1162. % change the version number.  You can see their actual outcome in a
  1163. % footnote to the title.
  1164. % The first thing that we do next is to get ourselves a new comment
  1165. % sign.  Because all sensible signs are already occupied, we will
  1166. % choose one that can only be entered indirectly:
  1167. % {\DoNotIndex{\^}^^A avoid misinterpretion !!!!! VERIFY  
  1168. %    \begin{macrocode}
  1169. \catcode`\^^A=14
  1170. %    \end{macrocode}
  1171. %    \SortIndex{\string^\string^A}{\string\verb\verbatimchar
  1172. %                                  \string^\string^A\verbatimchar
  1173. %                                  \encapchar main}
  1174. % \subsection{Macros surrounding the `definition parts'}
  1175. % \begin{macro}{\macrocode}
  1176. %    Parts of the macro definition will be surrounded by the
  1177. %    environment {\sf macrocode}.  Put more precisely, they will be
  1178. %    enclosed by a macro whose argument (the text to be set
  1179. %    `verbatim') is terminated by the string 
  1180. % \verb*+%    \end{macrocode}+.  Carefully note the number of spaces.
  1181. %    \verb+\macrocode+ is defined completely analogously to
  1182. %    \verb+\verbatim+, but because a few small changes were carried
  1183. %    out, almost all internal macros have got new names.  We start by
  1184. %    calling the macro \verb+\macro@code+, the macro which bears the
  1185. %    brunt of most of the work, such as \verb+\catcode+ reassignments,
  1186. %    etc.
  1187. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)}
  1188. %    \begin{macrocode}
  1189. \def\macrocode{\macro@code
  1190. %    \end{macrocode}
  1191. %    Then we take care that all spaces have the same width, and that
  1192. %    they are not discarded.
  1193. %    \begin{macrocode}
  1194.    \frenchspacing \@vobeyspaces
  1195. %    \end{macrocode}
  1196. %    Before closing, we need to call \verb+\xmacro@code+.  It is this
  1197. %    macro that expects an argument which is terminated by the above
  1198. %    string.  This way it is possible to keep the \verb+\catcode+
  1199. %    changes local.
  1200. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)}
  1201. % \changes{v1.5t}{89/11/07}{Common code moved to `macro@code.}
  1202. %    \begin{macrocode}
  1203.    \xmacro@code}
  1204. %    \end{macrocode}
  1205. % \end{macro}
  1206. % \begin{macro}{\macro@code}
  1207. %    We will now begin with the macro that does the actual work:
  1208. %    \begin{macrocode}
  1209. \def\macro@code{%
  1210. %    \end{macrocode}
  1211. %    In theory it should consist of a {\sf trivlist} environment, but
  1212. %    the empty space before and after the environment should not be
  1213. %    too large.
  1214. %    \begin{macrocode}
  1215.    \topsep \MacrocodeTopsep
  1216. %    \end{macrocode}
  1217. %    The next parameter we set is \verb+\@beginparpenalty+, in order
  1218. %    to prevent a page break before such an environment.
  1219. %    \begin{macrocode}
  1220.    \@beginparpenalty \predisplaypenalty
  1221. %    \end{macrocode}
  1222. %    We then start a \verb+\trivlist+, set \verb+\parskip+ back to
  1223. %    zero and start an empty \verb+\item+.
  1224. %    \begin{macrocode}
  1225.    \trivlist \parskip \z@ \item[]%
  1226. %    \end{macrocode}
  1227. %    Additionally, everything should be set in {\tt typewriter} font.
  1228. %    Some people might prefer it somewhat differently; because of this
  1229. %    the font choice is
  1230. %    macro-driven.\footnote{The font change has to be placed
  1231. %                       {\em after\/}
  1232. %                       the {\tt\bslash item}. Otherwise a change to
  1233. %                       {\tt\bslash baselineskip} will affect the
  1234. %                       paragraph above.}
  1235. %    \begin{macrocode}
  1236.    \macro@font
  1237. %    \end{macrocode}
  1238. %    Because \verb+\item+ sets various parameters, we have found it
  1239. %    necessary to alter some of these retrospectively.
  1240. %    \begin{macrocode}
  1241.    \leftskip\@totalleftmargin \advance\leftskip\MacroIndent
  1242.    \rightskip\z@ \parindent\z@ \parfillskip\@flushglue
  1243. %    \end{macrocode}
  1244. %    The next line consists of the \LaTeX{} definition of \verb+\par+
  1245. %    used in \verb+\verbatim+ and should result in blank lines being
  1246. %    shown as blank lines.
  1247. % \changes{v1.5l}{89/09/10}{Code line numbers supported.}
  1248. % \changes{v1.5t}{89/11/07}{Call `leavevmode to get `everypar on
  1249. %                           blank lines.}
  1250. % \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `par from
  1251. %                          verbatim.sty} 
  1252. %    \begin{macrocode}
  1253.    \blank@linefalse \def\par{\ifblank@line
  1254.                              \leavevmode\fi
  1255.                              \blank@linetrue\@@par
  1256.                              \penalty\interlinepenalty}
  1257. %    \end{macrocode}
  1258. %    What use is this definition of \verb+\par+\,?  We use the macro
  1259. %   \verb+\obeylines+ of \cite{book:KnuthA} which changes all \verb+^^M+
  1260. %    to \verb+\par+ so that each can control its own indentation.
  1261. %    Next we must also ensure that all special signs are normalized;
  1262. %    that is, they must be given \verb+\catcode+ $12$.
  1263. %    \begin{macrocode}
  1264.    \obeylines \let\do\@makeother \catcode`\`\active \@noligs \dospecials
  1265. %    \end{macrocode}
  1266. % \changes{v1.5t}{89/11/07}{Common code added.}
  1267. % \changes{v1.5w}{90/02/05}{Skip of `@totalleftmargin added.}
  1268. % If indexing by code lines is switched on the line number is
  1269. % incremented and set appropriately.  We also check whether the start of
  1270. % the next line indicates a {\tt docstrip} module directive and process
  1271. % it appropriately if so using "\check@module".
  1272. %    \begin{macrocode}
  1273.    \global\@newlistfalse
  1274.    \global\@minipagefalse
  1275.    \ifcodeline@index
  1276.      \everypar{\global\advance\c@CodelineNo\@ne
  1277.                \llap{\theCodelineNo\ \hskip\@totalleftmargin}%
  1278.                \check@module}%
  1279.    \else \everypar{\check@module}%
  1280.    \fi
  1281. %    \end{macrocode}
  1282. %    We also initialize the cross-referencing feature by calling
  1283. %    \verb+\init@crossref+. This will start the scanning mechanism
  1284. %    when encountering an escape character.
  1285. %    \begin{macrocode}
  1286.    \init@crossref}
  1287. %    \end{macrocode}
  1288. % \end{macro}
  1289. % \begin{macro}{\ifblank@line}
  1290. % \begin{macro}{\blank@linetrue}
  1291. % \begin{macro}{\blank@linefalse}
  1292. %    \verb+\ifblank@line+ is the switch used in the definition above.
  1293. %    In the original {\sf verbatim} environment the \verb+\if@tempswa+
  1294. %    switch is used. This is dangerous because its value may change
  1295. %    while processing lines in the {\sf macrocode} environment.
  1296. %    \begin{macrocode}
  1297. \newif\ifblank@line
  1298. %    \end{macrocode}
  1299. % \end{macro}
  1300. % \end{macro}
  1301. % \end{macro}
  1302. % \begin{macro}{\endmacrocode}
  1303. %    Because we have begun a {\sf trivlist} environment in the {\sf
  1304. %    macrocode} environment, we must also end it.  We must also act on
  1305. %    the value of the "pm@module" flag (see below) and empty
  1306. %    "\everypar".
  1307. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)}
  1308. %    \begin{macrocode}
  1309. \def\endmacrocode{%
  1310.                  \ifpm@module \endgroup \pm@modulefalse \fi
  1311.                  \everypar{}%
  1312.                  \global\@inlabelfalse
  1313.                  \endtrivlist
  1314. %    \end{macrocode}
  1315. %    Additionally \verb+\close@crossref+ is used to do anything needed
  1316. %    to end the cross-referencing mechanism.
  1317. %    \begin{macrocode}
  1318.                  \close@crossref}
  1319. %    \end{macrocode}
  1320. % \end{macro}
  1321. % \begin{macro}{\MacroFont}
  1322. %    Here is the default definition for the \verb+\MacroFont+ macro.
  1323. %    If the new font selection scheme is in use we suppress changes
  1324. %    of math fonts thereby making doc much faster.
  1325. % \changes{v1.5x}{90/02/17}{`math@fontsfalse added for new font sel.}
  1326. % \changes{v1.7a}{92/03/13}{Added `reset@font for NFSS.}
  1327. %    \begin{macrocode}
  1328. \@ifundefined{MacroFont}{%
  1329.   \ifx\undefined\selectfont
  1330.     \def\MacroFont{\small\tt}\else
  1331.     \def\MacroFont{\math@fontsfalse\reset@font\small\tt}\fi
  1332.   }{}
  1333. %    \end{macrocode}
  1334. % \end{macro}
  1335. % \begin{macro}{\AltMacroFont}
  1336. % \begin{macro}{\macro@font}
  1337. % \changes{v1.7a}{92/03/12}{Added to support distinction of modules.}
  1338. % \changes{v1.7c}{92/03/26}{Altered font change for OFSS.}
  1339. % Although most of the macro code is set in "\MacroFont" we want to be
  1340. % able to switch to indicate module code set in "\AltMacroFont".
  1341. % "\macro@font" keeps track of which one we're using.  We can't do the
  1342. % same thing sensibly in OFSS as in NFSS.
  1343. %    \begin{macrocode}
  1344. \@ifundefined{AltMacroFont}{%
  1345.   \ifx\undefined\selectfont
  1346.     \def\AltMacroFont{\small\tt}\else
  1347.     \def\AltMacroFont{\math@fontsfalse\small\reset@font\it\tt}\fi
  1348.   }{}
  1349. \let\macro@font=\MacroFont
  1350. %    \end{macrocode}
  1351. % \end{macro}
  1352. % \end{macro}
  1353. % \begin{macro}{\check@module}
  1354. % \begin{macro}{\ifpm@module}
  1355. % \changes{v1.7a}{92/03/12}{Added.}
  1356. % This is inserted by "\everypar" at the start of each macrocode line to
  1357. % check whether it starts with module information.  (Such information is
  1358. % of the form "%<"\meta{switch}">", where the "%" must be at the
  1359. % start of the line and \meta{switch} comprises names with various
  1360. % possible separators and a possible leading "+", "-", "*" or "/"
  1361. % \cite{art:docstrip}.  All that concerns us here is what the first
  1362. % character of \meta{switch} is.)  First it checks the "pm@module" 
  1363. % flag in case the previous line had a non-block module
  1364. % directive i.e., not "%<*" or "%</"; if it did we need to close the
  1365. % group it started and unset the flag.  "\check@module" looks ahead at
  1366. % the next token and then calls "\ch@percent" to take action depending
  1367. % on whether or not it's a "%"; we don't want to expand the token at
  1368. % this stage.  This is all done conditionally so it can be turned off
  1369. % if it causes problems with code that wasn't designed to be {\tt
  1370. % docstrip}ped.
  1371. %    \begin{macrocode}
  1372. \def\check@module{%
  1373.   \ifcheck@modules
  1374.     \ifpm@module \endgroup \pm@modulefalse \fi
  1375.     \expandafter\futurelet\expandafter\next\expandafter\ch@percent
  1376.   \fi}
  1377. \newif\ifpm@module
  1378. %    \end{macrocode}
  1379. % \end{macro}
  1380. % \end{macro}
  1381. % \begin{macro}{\DontCheckModules}
  1382. % \begin{macro}{\CheckModules}
  1383. % \changes{v1.7a}{92/03/12}{Added.}
  1384. % \begin{macro}{\ifcheck@modules}
  1385. % Here are two driver-file interface macros for turning the module
  1386. % checking on and off using the "check@modules" switch.
  1387. %    \begin{macrocode}
  1388. \def\DontCheckModules{\check@modulesfalse}
  1389. \def\CheckModules{\check@modulestrue}
  1390. \newif\ifcheck@modules  \check@modulestrue
  1391. %    \end{macrocode}
  1392. % \end{macro}
  1393. % \end{macro}
  1394. % \end{macro}
  1395. % \begin{macro}{\ch@percent}
  1396. % \changes{v1.7a}{92/03/12}{Added.}
  1397. % If the lookahead token in "\next" is $"%"_{12}$ we go on to check
  1398. % whether the following one is "<" and otherwise do nothing.  Note the
  1399. % "\expandafter" to get past the "\fi".
  1400. %    \begin{macrocode}
  1401. \def\ch@percent{%
  1402.   \if \percentchar\next
  1403.     \expandafter\check@angle
  1404.   \fi}
  1405. %    \end{macrocode}
  1406. % \end{macro}
  1407. % \begin{macro}{\check@angle}
  1408. % \changes{v1.7a}{92/03/12}{Added.}
  1409. % Before looking ahead for the "<" the "%" is gobbled by the
  1410. % argument here.
  1411. %    \begin{macrocode}
  1412. \def\check@angle#1{\futurelet\next\ch@angle}
  1413. %    \end{macrocode}
  1414. % \end{macro}
  1415. % \begin{macro}{\ch@angle}
  1416. % \changes{v1.7a}{92/03/12}{Added.}
  1417. % If the current lookahead token is "<" we are defined to be
  1418. % processing a module directive can go on to look for "+"
  1419. % etc.; otherwise we must put back the gobbled "%".
  1420. %    \begin{macrocode}
  1421. \def\ch@angle{\if<\next
  1422.     \expandafter\ch@plus@etc 
  1423.   \else \percentchar \fi}
  1424. %    \end{macrocode}
  1425. % \end{macro}
  1426. % \begin{macro}{\ch@plus@etc}
  1427. % \begin{macro}{\check@plus@etc}
  1428. % \changes{v1.7a}{92/03/12}{Added.}
  1429. % We now have to decide what sort of a directive we're dealing with
  1430. % and do the right thing with it.
  1431. %    \begin{macrocode}
  1432. \def\ch@plus@etc<{\futurelet\next\check@plus@etc}
  1433. \def\check@plus@etc{%
  1434.     \if +\next
  1435.       \let\next\pm@module
  1436.     \else\if -\next
  1437.       \let\next\pm@module
  1438.     \else\if *\next
  1439.       \let\next\star@module
  1440.     \else\if /\next
  1441.       \let\next\slash@module
  1442.     \else
  1443.       \let\next\pm@module
  1444.     \fi\fi\fi\fi
  1445.     \next}
  1446. %    \end{macrocode}
  1447. % \end{macro}
  1448. % \end{macro}
  1449. % \begin{macro}{\pm@module}
  1450. % If we're not dealing with a block
  1451. % directive ("*" or "/") i.e., it's a single special line, we set
  1452. % everything up to the next ">" appropriately and then change to the
  1453. % special macro font inside a group which will be ended at the start
  1454. % of the next line.  If the apparent module directive is missing the
  1455. % terminating ">" this will lose, but then so will the {\tt docstrip}
  1456. % implementation.  An alternative strategy would be to have
  1457. % "\pm@module" make ">" active and clear a flag set here to indicate
  1458. % processing the directive.  Appropriate action could then be taken if
  1459. % the flag was found still to be set when processing the next line.
  1460. % \changes{v1.7a}{92/03/12}{Added.} 
  1461. % \changes{v1.7i}{92/07/11}{Support for fonts depending on nesting.}
  1462. %    \begin{macrocode}
  1463. \def\pm@module#1>{\pm@moduletrue
  1464.    \Module{#1}\begingroup 
  1465. %    \end{macrocode}
  1466. %    We switch to a special font as soon the nesting is higher than
  1467. %    the current value of "\c@StandardModuleDepth". We do a local
  1468. %    update to the "\guard@level" here which will be restored after
  1469. %    the current input line.
  1470. %    \begin{macrocode}
  1471.      \advance\guard@level\@ne
  1472.      \ifnum\guard@level>\c@StandardModuleDepth\AltMacroFont\fi
  1473. %    \end{macrocode}
  1474. % \end{macro}
  1475. % \begin{macro}{\star@module}
  1476. % \begin{macro}{\slash@module}
  1477. % \changes{v1.7a}{92/03/12}{Added.}
  1478. % \changes{v1.7f}{92/05/16}{Take account of nested guards.}
  1479. % \changes{v1.7i}{92/07/11}{Add counter to determine when to switch to
  1480. %                           special font.}
  1481. % If the start or end of a module {\em block\/} is indicated, after
  1482. % setting the guard we have to check whether a change in the macrocode
  1483. % font should be done.  This will be the case if we are already inside
  1484. % a block or are ending the outermost block.  If so, we globally
  1485. % toggle the font for subsequent macrocode sections between the normal
  1486. % and special form, switching to the new one immediately.
  1487. % \changes{v1.7i}{92/07/17}{Support for fonts depending on module
  1488. %                           nesting}
  1489. %    \begin{macrocode}
  1490. \def\star@module#1>{%
  1491.   \Module{#1}%
  1492.   \global \advance \guard@level\@ne
  1493.   \ifnum \guard@level>\c@StandardModuleDepth
  1494.     \global\let\macro@font=\AltMacroFont \macro@font
  1495.   \fi}
  1496. \def\slash@module#1>{%
  1497.   \Module{#1}%
  1498.   \global \advance \guard@level\m@ne
  1499.   \ifnum \guard@level=\c@StandardModuleDepth
  1500.     \global\let\macro@font\MacroFont  \macro@font
  1501.   \fi
  1502. %    \end{macrocode}
  1503. % \end{macro}
  1504. % \end{macro}
  1505. %  \begin{macro}{\c@StandardModuleDepth}
  1506. % \changes{v1.7i}{92/07/11}{Counter added.}
  1507. %    Counter defining up to which level modules are considered part of
  1508. %    the main code. If, for  example, the whole code is surrounded by
  1509. %    a |%<*style>| module we better set this counter to |1| to avoid
  1510. %    getting the whole code be displayed in typewriter italic.
  1511. %    \begin{macrocode}
  1512. \newcounter{StandardModuleDepth}
  1513. %    \end{macrocode}
  1514. %  \end{macro}
  1515. % \begin{macro}{\guard@level}
  1516. % \changes{v1.7f}{92/05/16}{Added.}
  1517. % We need a counter to keep track of the guard nesting.
  1518. %    \begin{macrocode}
  1519. \newcount \guard@level
  1520. %    \end{macrocode}
  1521. % \end{macro}
  1522. % \begin{macro}{\Module}
  1523. % \changes{v1.7a}{92/03/12}{Added.}
  1524. % \changes{v1.7d}{92/04/25}{Use sans font for modules.}
  1525. % This provides a hook to determine the way the module directive is
  1526. % set.  It gets as argument everything between the angle brackets.
  1527. % The default is to set the contents in sans serif text between
  1528. % $\langle\,\rangle$ with the special characters suitably "\mathcode"d
  1529. % by "\mod@math@codes".  (You can't just set it in a sans text font
  1530. % because normally "|" will print as an em-dash.)  This is done
  1531. % differently depending on whether we have the NFSS or the old one.  In
  1532. % the latter case we can easily change "\fam" appropriately.
  1533. %    \begin{macrocode}
  1534. \@ifundefined{Module}{%
  1535.   \ifx\undefined\selectfont
  1536.     \def\Module#1{{\mod@math@codes$\fam\sffam\langle #1\rangle$}}
  1537. %    \end{macrocode}
  1538. % With NFSS what we probably {\em should\/} do is change to a new
  1539. % "\mathversion" but I (Dave Love) haven't spotted an easy way to do so
  1540. % correctly if the document uses a version other than "normal".  (We
  1541. % need to know in what font to set the other groups.)  This uses a new
  1542. % math alphabet rather than version and consequently has to worry about
  1543. % whether we're using {\sf oldlfont} or not.  I expect there's a better
  1544. % way\ldots
  1545. %    \begin{macrocode}
  1546.   \else
  1547.     \expandafter\ifx\csname ds@oldlfont\endcsname\relax
  1548.       \def\Module#1{{\mod@math@codes$\langle\sfmath{#1}\rangle$}}
  1549.     \else
  1550.       \def\Module#1{{\mod@math@codes$\langle{\sfmath #1}\rangle$}}
  1551.     \fi
  1552.   \fi}{}
  1553. %    \end{macrocode}
  1554. % \end{macro}
  1555. % \begin{macro}{\mod@math@codes}
  1556. % \changes{v1.7c}{92/03/26}{Added.}
  1557. % As well as `words', the module directive text might contain any of the
  1558. % characters "*/+-,&|!()" for the current version of {\sf docstrip}.  We
  1559. % only need special action for two of them in the math code changing
  1560. % required above: "|" is changed to a "\mathop" (it's normally
  1561. % \verb+"026A+) and "&" is also made a "\mathop", but in family 0.
  1562. % Remember that "&" will not have a special catcode when it's
  1563. % encountered. 
  1564. %    \begin{macrocode}
  1565. \def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026}
  1566. %    \end{macrocode}
  1567. % \end{macro}
  1568. % \begin{macro}{\sfmath}
  1569. % \changes{v1.7c}{92/03/26}{Added.}
  1570. % \changes{v1.7d}{92/04/25}{Use sans font for modules.}
  1571. % If NFSS is in use we need a new math alphabet which uses a sans serif
  1572. % font.
  1573. %    \begin{macrocode}
  1574. \ifx\selectfont\undefined
  1575. \else
  1576.   \ifx\sfmath\undefined
  1577.     \newmathalphabet*{\sfmath}{\sfdefault}{m}{n}\fi
  1578. %    \end{macrocode}
  1579. % \end{macro}
  1580. % \begin{macro}{\MacrocodeTopsep}
  1581. % \begin{macro}{\MacroIndent}
  1582. %    In the code above, we have used two registers. Therefore we have
  1583. %    to allocate them. The default values might be overwritten with
  1584. %    the help of the \verb+\DocstyleParms+ macro.
  1585. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  1586. % \changes{v1.5y}{90/02/24}{Default changed.}
  1587. % \changes{v1.6b}{90/06/15}{`rm moved before `scriptsize to
  1588. %                           avoid unnecessary fontwarning.}
  1589. %    \begin{macrocode}
  1590. \newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt
  1591. \newdimen\MacroIndent    
  1592. \settowidth\MacroIndent{\rm\scriptsize 00\ }
  1593. %    \end{macrocode}
  1594. % \end{macro}
  1595. % \end{macro}
  1596. % \begin{macro}{\macrocode*}
  1597. % \begin{macro}{\endmacrocode*}
  1598. %    Just as in the {\sf verbatim} environment, there is also a `star'
  1599. %    variant of the {\sf macrocode} environment in which a space is
  1600. %    shown by the symbol \verb*+ +.  Until this moment, I have not yet
  1601. %    used it (it will be used in the description of the definition of
  1602. %    \verb+\xmacro@code+ below) but it's exactly on this one occasion
  1603. %    {\em here\/} that you can't use it
  1604. %    (cf.\ M\"unchhausens Marsh problem)\footnote{Karl Friedrich
  1605. %         Hieronymus Frhr.\ v.\ M\"unchhausen (*1720, \dag1797).
  1606. %         Several books were written about fantastic adventures
  1607. %         supposedly told by him (see \cite{book:Raspe} or
  1608. %         \cite{book:Buerger}). In one story he escaped from the
  1609. %         marsh by pulling himself out by his hair.}
  1610. %    directly. Because of this, on this one occasion we'll cheat
  1611. %    around the problem with an additional comment character.  But now
  1612. %    back to \verb+\macrocode*+. We start with the macro
  1613. %    \verb+\macro@code+ which prepares everything and then call the
  1614. %    macro \verb+\sxmacro@code+ whose argument is terminated by the
  1615. %    string \verb*+%    \end{macrocode*}+.
  1616. %    \begin{macrocode}
  1617. \@namedef{macrocode*}{\macro@code\sxmacro@code}
  1618. %    \end{macrocode}
  1619. %    As we know, \verb+\sxmacro@code+ and then \verb+\end{macrocode*}+
  1620. %    (the macro, not the string), will be executed, so that for a
  1621. %    happy ending we still need to define the macro
  1622. %    \verb+\endmacrocode*+.
  1623. %    \begin{macrocode}
  1624. \expandafter\let\csname endmacrocode*\endcsname = \endmacrocode
  1625. %    \end{macrocode}
  1626. % \end{macro}
  1627. % \end{macro}
  1628. % \begin{macro}{\xmacro@code}
  1629. \catcode`\!=\catcode`\%   ^^A In this section there must not be
  1630.                               ^^A any exclamation marks.
  1631.                               ^^A
  1632. %    As already mentioned, the macro \verb+\xmacro@code+ expects an
  1633. %    argument delimited by the string \verb*+%    \end{macrocode}+.  At
  1634. %    the moment that this macro is called, the \verb+\catcode+ of
  1635. %    \TeX's special characters are 12 (`other') or 13 (`active').
  1636. %    Because of this we need to utilize a different escape character
  1637. %    during the definition.  This happens locally.
  1638. %    \begin{macrocode*}
  1639. \begingroup
  1640. \catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@
  1641. %    \end{macrocode*}
  1642. %    Additionally, we need to ensure that the symbols in the above
  1643. %    string contain the \verb+\catcode+$\,$s which are available
  1644. %    within the {\sf macrocode} environment.
  1645. %    \begin{macrocode*}
  1646. \catcode`\{=12 \catcode`\}=12
  1647. \catcode`\%=12 \catcode`\ =\active \catcode`\\=\active
  1648. !%    \end{macrocode*}
  1649. !    Next follows the actual definition of  \verb+\macro@code+;
  1650. !    notice the
  1651. !    use of the new escape character.  We manage to get the argument
  1652. !    surrounded by the string \verb+\end{macrocode}+, but at the end
  1653. !    however, in spite of the actual characters used during the
  1654. !    definition of
  1655. !    this macro, \verb+\end+ with the argument \verb+{macrocode}+
  1656. !    will be executed, to ensure a balanced environment.
  1657. !    \begin{macrocode*}
  1658. |gdef|xmacro@code#1%    \end{macrocode}[#1|end[macrocode]]
  1659. !%    \end{macrocode*}
  1660. ! \begin{macro}{\sxmacro@code}
  1661. !    The definition of \verb+\sxmacro@code+ is completely analogous,
  1662. !    only
  1663. !    here a slightly different terminating string will be used.
  1664. !    Note that the space is not active in this environment.
  1665. !    \begin{macrocode}
  1666. |catcode`| =12
  1667. |gdef|sxmacro@code#1%    \end{macrocode*}[#1|end[macrocode*]]
  1668. !%    \end{macrocode}
  1669. !    because the \verb+\catcode+ changes have been made local by
  1670. !    commencing a
  1671. !    new group, there now follows the matching \verb+\endgroup+
  1672. !    in a rather
  1673. !    unusual style of writing.
  1674. !    \begin{macrocode}
  1675. |endgroup
  1676. !%    \end{macrocode}
  1677. \catcode`\!=12
  1678. % \end{macro}
  1679. % \end{macro}
  1680. % \subsection{Macros for the `documentation parts'}
  1681. % \begin{macro}{\DescribeMacro}
  1682. % \begin{macro}{\Describe@Macro}
  1683. % \changes{v1.5v}{90/01/28}{Macro added.}
  1684. % \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.}
  1685. % \begin{macro}{\DescribeEnv}
  1686. % \begin{macro}{\Describe@Env}
  1687. % \changes{v1.5v}{90/01/28}{Macro added.}
  1688. % \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.}
  1689. %    The \verb+\DescribeMacro+ and \verb+\DescribeEnv+ macros should
  1690. %    print their arguments in the margin and produce an index entry.
  1691. %    We simply use \verb+\marginpar+ to get the desired result. This
  1692. %    is however not the best solution because the labels might be
  1693. %    slightly misplaced. One also might get a lot of `marginpar moved'
  1694. %    messages which are hard-wired into the \LaTeX{} output
  1695. %    routine.\footnote{It might be better to change these macros into
  1696. %    environments like the {\sf macro} environment.} First we change
  1697. %    to horizontal mode if necessary. The \LaTeX{} macros
  1698. %    \verb+\@bsphack+ and \verb+\@esphack+ are used to make those
  1699. %    commands invisible (i.e.\ to normalize the surrounding space and
  1700. %    to make the \verb+\spacefactor+ transparent).
  1701. % \changes{v1.5v}{90/01/28}{`MakePrivateLetters added.}
  1702. %    \begin{macrocode}
  1703. \def\DescribeMacro{\leavevmode\@bsphack
  1704. %    \end{macrocode}
  1705. %    When documenting the code for the {\tt amstex.sty} option we
  1706. %    encountered a bug: the \verb+\catcode+ of \verb+@+ was active and
  1707. %    therefore couldn't be used in command names. So we first have to
  1708. %    make sure that we get all \verb+\catcode+s right by calling
  1709. %    \verb+\MakePrivateLetters+ inside a group. Then we call
  1710. %    \verb+\Describe@Macro+ to do the work.
  1711. %    \begin{macrocode}
  1712.    \begingroup\MakePrivateLetters\Describe@Macro}
  1713. \def\Describe@Macro#1{\endgroup
  1714.               \marginpar{\raggedleft\PrintDescribeMacro{#1}}%
  1715. %    \end{macrocode}
  1716. %    Note the use of \verb+\raggedleft+ to place the output flushed
  1717. %    right. Finally we call a macro which produces the actual index
  1718. %    entry and finish with \verb+\@esphack+ to leave no
  1719. %    trace.\footnote{The whole mechanism won't work because
  1720. %                    of the {\tt\bslash leavevmode} in front.
  1721. %                    As a temporary change {\tt\bslash ignorespaces}
  1722. %                    is added.}
  1723. %    \begin{macrocode}
  1724.               \SpecialUsageIndex{#1}\@esphack\ignorespaces}
  1725. %    \end{macrocode}
  1726. %    The \verb+\DescribeEnv+ macro is completely analogous.
  1727. % \changes{v1.5v}{90/01/28}{`MakePrivateLetters added.}
  1728. %    \begin{macrocode}
  1729. \def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters
  1730.   \Describe@Env}
  1731. \def\Describe@Env#1{\endgroup
  1732.               \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
  1733.               \SpecialEnvIndex{#1}\@esphack\ignorespaces}
  1734. %    \end{macrocode}
  1735. %    To put the labels in the left margin we have to use the
  1736. %    \verb+\reversemarginpar+ declaration. (This means that the {\tt
  1737. %    doc.sty} can't be used with all style options.) We also make the
  1738. %    \verb+\marginparpush+ zero and \verb+\marginparwidth+ suitably
  1739. %    wide.
  1740. % \changes{v1.5d}{89/4/28}{marginparwith setting added.}
  1741. %    \begin{macrocode}
  1742. \reversemarginpar
  1743. \setlength\marginparpush{0pt}  \setlength\marginparwidth{8pc}
  1744. %    \end{macrocode}
  1745. % \end{macro}
  1746. % \end{macro}
  1747. % \end{macro}
  1748. % \end{macro}
  1749. % \begin{macro}{\bslash}
  1750. % \changes{v1.7a}{92/02/26}{Moved `bslash documentation to `user
  1751. %                           interface' part}
  1752. %    We start a new group in which to hide the alteration of
  1753. %    \verb+\catcode+$\,$s, and make \verb+|+ introduce commands,
  1754. %    whilst \verb+\+ becomes an `other' character.
  1755. %    \begin{macrocode}
  1756. {\catcode`\|=\z@ \catcode`\\=12
  1757. %    \end{macrocode}
  1758. %    Now we are able to define \verb+\bslash+ (globally) to generate a
  1759. %    backslash of \verb+\catcode+ `other'.  We then close this group,
  1760. %    restoring original \verb+\catcode+$\,$s.
  1761. %    \SpecialEscapechar{\|}
  1762. %    \begin{macrocode}
  1763. |gdef|bslash{\}}
  1764. %    \end{macrocode}
  1765. % \end{macro}
  1766. % \begin{macro}{\verbatim}
  1767. % \begin{macro}{\verbatim*}
  1768. % \changes{v1.7i}{92/07/12}{Added changed definition for verbatim!*.}
  1769. %    The {\sf verbatim} environment holds no secrets; it consists of
  1770. %    the normal \LaTeX{} environment.  We also set the
  1771. %    \verb+\@beginparpenalty+ and change to the font given by
  1772. %    \verb+\MacroFont+.
  1773. %    \begin{macrocode}
  1774. \def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim
  1775.               \MacroFont \frenchspacing \@vobeyspaces \@xverbatim}
  1776. %    \end{macrocode}
  1777. %    We deal in a similar way with the star form of this environment.
  1778. %    \begin{macrocode}
  1779. \@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim
  1780.               \MacroFont \@sxverbatim}
  1781. %    \end{macrocode}
  1782. % \end{macro}
  1783. % \end{macro}
  1784. % \begin{macro}{\@verbatim}
  1785. %    Additionally we redefine the \verb+\@verbatim+ macro so that it
  1786. %    suppresses \verb+%+ characters at the beginning of the line.  The
  1787. %    first lines are copied literally from {\tt latex.tex}.
  1788. % \changes{v1.7i}{92/07/12}{Added `@@par to clear possible `parshape.}
  1789. %    \begin{macrocode}
  1790. \def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi
  1791.       \leftskip\@totalleftmargin\rightskip\z@
  1792.       \parindent\z@\parfillskip\@flushglue\parskip\z@
  1793.       \@@par
  1794.       \@tempswafalse
  1795. %    \end{macrocode}
  1796. %    \verb+\@verbatim+ sets \verb+^^M+, the end of line character, to
  1797. %    be equal to \verb+\par+.  This control sequence is redefined
  1798. %    here; \verb+\@@par+ is the paragraph primitive of \TeX.
  1799. %    \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `par from
  1800. %                             verbatim.sty} 
  1801. %    \begin{macrocode}
  1802.  \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par
  1803.           \penalty\interlinepenalty
  1804. %    \end{macrocode}
  1805. %    We add a control sequence \verb+\check@percent+ to the definition
  1806. %    of \verb+\par+ whose task it is to check for a percent character.
  1807. %    \begin{macrocode}
  1808.    \check@percent}%
  1809. %    \end{macrocode}
  1810. %    The rest is again copied literally from {\tt latex.tex} (less
  1811. %    "\tt").
  1812. % \changes{v1.7a}{92/02/26}{Removed redundant `tt.}
  1813. %    \begin{macrocode}
  1814.  \obeylines \catcode`\`\active \@noligs \let\do\@makeother
  1815.  \dospecials}
  1816. %    \end{macrocode}
  1817. % \end{macro}
  1818. % \begin{macro}{\check@percent}
  1819. %    Finally we define \verb+\check@percent+.  Since this must compare
  1820. %    a character with a percent sign we must first (locally) change
  1821. %    percent's \verb+\catcode+ so that it is seen by \TeX.  The
  1822. %    definition itself is nearly trivial: grab the following
  1823. %    character, check if it is a \verb+%+, and insert it again if not.
  1824. %    At the end of the {\sf verbatim} environment this macro will peek
  1825. %    at the next input line. In that case the argument to
  1826. %    \verb+\check@percent+ might be a \verb+\par+ or a macro with
  1827. %    arguments. Therefore we make the definition \verb+\long+
  1828. %    (\verb+\par+ allowed) and use the normal \verb+\next+ mechanism
  1829. %    to reinsert the argument after the \verb+\fi+ if necessary.
  1830. %  \changes{v1.5i}{89/06/07}{Definition changed to `long'}
  1831. %  \changes{v1.5i}{89/06/07}{Macro `next' used to guard against
  1832. %                            macro with arguments}
  1833. %    There is a subtle problem here, the equal sign between
  1834. %    \verb+\next+ and \verb+#1+ is actually necessary. Do you see why?
  1835. %    The omission of this token once caused a funny error.
  1836. %  \changes{v1.5u}{89/11/14}{equal sign added.}
  1837. %    \begin{macrocode}
  1838. {\catcode`\%=12 
  1839.  \long\gdef\check@percent#1{\ifx #1%\let\next\@empty \else
  1840.                                     \let\next=#1\fi \next}}
  1841. %    \end{macrocode}
  1842. % \end{macro}
  1843. % \begin{macro}{\verb}
  1844. % \changes{v1.7a}{92/02/27}{Now warns about newlines (from
  1845. %                           newdoc with `@noligs added).}
  1846. % We re-define "\verb" to check for newlines in its argument since a
  1847. % missing delimiter is difficult to detect in {\sf doc} source.
  1848. % Although the code is somewhat different, the
  1849. % method follows \cite{art:verbatim}, which should be
  1850. % consulted for commentary.  Perhaps there should be a font-changing
  1851. % hook rather than just using "\tt", but if so it probably should be
  1852. % different from "\MacroFont" since that normally includes "\small"
  1853. % and would look wrong inline.  (There's no particular reason for
  1854. % using lower-casing here to
  1855. % splice in the relevant character, rather than the upper-casing used in
  1856. % the definition of "\SpecialEscapechar"
  1857. % (\S\ref{sect:specialescapechar}); remember that the case
  1858. % shift doesn't touch the control sequence tokens.)
  1859. % \changes{v1.7a}{92/02/28}{Added math math check (from verbatim.sty).}
  1860. %    \begin{macrocode}
  1861. \begingroup
  1862.   \lccode`\~=`\^^M
  1863.   \lowercase{%
  1864.     \gdef\verb{\relax
  1865.       \ifmmode \hbox \else \leavevmode\null \fi
  1866.       \bgroup
  1867.       \tt   \catcode`\`\active \@noligs
  1868.       \let~\verb@err
  1869.       \catcode`\^^M\active
  1870.       \let\do\@makeother \dospecials
  1871.       \@ifstar\@sverb{\@vobeyspaces \frenchspacing \@sverb}}}
  1872. \endgroup
  1873. \def\verb@err{\egroup\@latexerr{\string\verb\space
  1874.                command ended by end of line.}\@ehc}
  1875. %    \end{macrocode}
  1876. % \end{macro}
  1877. % \begin{macro}{\@sverb}
  1878. % \changes{v1.7a}{92/02/27}{Added for `verb change.}
  1879. % \changes{v1.7a}{92/02/28}{Now same as in verbatim.sty.}
  1880. % See \cite{art:verbatim} for commentary.
  1881. %    \begin{macrocode}
  1882. \def\@sverb#1{%
  1883.   \catcode`#1\active  \lccode`\~`#1%
  1884.   \lowercase{\let~\egroup}}
  1885. %    \end{macrocode}
  1886. % \end{macro}
  1887. % \begin{macro}{\macro}
  1888. % \begin{macro}{\m@cro@}
  1889. % \changes{v1.5v}{90/01/28}{`macro@ renamed to `m@cro@ since AmSTeX
  1890. %      defines another macro of the same name.}
  1891. % \begin{macro}{\macro@cnt}
  1892. % \begin{macro}{\macro@level}
  1893. %    \label{page:macro} The {\sf macro} environment is implemented as
  1894. %    a {\sf trivlist} environment, whereby in order that the macro
  1895. %    names can be placed under one another in the margin
  1896. %    (corresponding to the macro's nesting depth), the macro
  1897. %    \verb+\makelabel+ must be altered.  In order to store the nesting
  1898. %    depth, we use a counter. We also need a counter to count the
  1899. %    number of nested {\sf macro} environments.
  1900. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  1901. %    \begin{macrocode}
  1902. \newcount\macro@cnt \macro@cnt=0
  1903. \newcount\macro@level \macro@level=0
  1904. %    \end{macrocode}
  1905. %    The environment takes an argument---the macro name to be
  1906. %    described.  Since this name may contain special `letters' we have
  1907. %    to re-\verb+\catcode+ them before scanning the argument. This is
  1908. %    done by the \verb+\MakePrivateLetters+ macro.  On toplevel we
  1909. %    start with \verb+\begingroup+ otherwise we simply re-catcode the
  1910. %    special letters and call \verb+\m@cro@+. Therefore the
  1911. %    \verb+\endgroup+ at the start of this macro will cancel the group
  1912. %    opened by the \verb+\begin+ macro if we are already inside a {\sf
  1913. %    macro} environment. This avoids problems with the save-stack on
  1914. %    small systems since then the \verb+\trivlist+ used later on will
  1915. %    not put anything onto this stack.
  1916. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  1917. % \changes{v1.7a}{92/02/26}{Catcode backslash to other (from newdoc).}
  1918. %    \begin{macrocode}
  1919. \def\macro{%
  1920.    \ifnum\macro@level=\z@ \begingroup \fi
  1921.    \catcode`\\12
  1922.    \MakePrivateLetters \m@cro@}
  1923. %    \end{macrocode}
  1924. %    After scanning the argument we close the group to get the normal
  1925. %    \verb+\catcode+$\,$s back. Then we assign a special value to
  1926. %    \verb+\topsep+ and start a {\sf trivlist} environment.
  1927. %    Additionally we advance the \verb+\macro@level+ counter to keep
  1928. %    track of the number of nested {\sf macro} environments.
  1929. % \changes{v1.5f}{89/5/07}{MacroTopsep parameter added.}
  1930. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  1931. %    \begin{macrocode}
  1932. \long\def\m@cro@#1{\endgroup \topsep\MacroTopsep \trivlist
  1933.    \advance\macro@level\@ne
  1934. %    \end{macrocode}
  1935. % We also save the name being described in \verb+\saved@macroname+ for
  1936. % use in conjunction with the \verb+\changes+ macro.
  1937. %    \begin{macrocode}
  1938.    \edef\saved@macroname{\string#1}%
  1939. %    \end{macrocode}
  1940. %    Now there follows a variation of \verb+\makelabel+ which is used
  1941. %    should the environment not be nested, or should it lie between
  1942. %    two successive \verb+\begin{macro}+ instructions or explanatory
  1943. %    text.  One can recognize this with the switch \verb+\if@inlabel+
  1944. %    which will be \verb+true+ in the case of successive \verb+\item+
  1945. %    commands.
  1946. %    \begin{macrocode}
  1947.   \def\makelabel##1{\llap{##1}}%
  1948. %    \end{macrocode}
  1949. %    If \verb+@inlabel+ is \verb+true+ and if $\verb=\macro@cnt= > 0$
  1950. %    then the above definition needs to be changed, because in this
  1951. %    case \LaTeX{} would otherwise put the labels all on the same line
  1952. %    and this would lead to them being overprinted on top of each
  1953. %    other.  Because of this \verb+\makelabel+ needs to be redefined
  1954. %    in this case.
  1955. %    \begin{macrocode}
  1956.   \if@inlabel
  1957. %    \end{macrocode}
  1958. %    If \verb+\macro@cnt+ has the value $1$, then we redefine
  1959. %    \verb+\makelabel+ so that the label will be positioned in the
  1960. %    second line of the margin.  As a result of this, two macro names
  1961. %    appear correctly, one under the other.  It's important whilst
  1962. %    doing this that the generated label box is not allowed to have
  1963. %    more depth than a normal line since otherwise the distance
  1964. %    between the first two text lines of \TeX{} will be incorrectly
  1965. %    calculated. The definition should then look like:
  1966. %\begin{verbatim}
  1967. %     \def\makelabel##1{\llap{\vtop to \baselineskip
  1968. %          {\hbox{\strut}\hbox{##1}\vss}}}
  1969. %\end{verbatim}
  1970. %    Completely analogous to this is the case where labels need to be
  1971. %    placed one under the other.  The lines above are only an example
  1972. %    typeset with the {\sf verbatim} environment. To produce the real
  1973. %    definition we save the value of \verb+\macro@cnt+ in
  1974. %    \verb+\count@+ and empty the temp macro \verb+\@tempa+ for later
  1975. %    use.
  1976. %    \begin{macrocode}
  1977.     \let\@tempa\@empty \count@\macro@cnt
  1978. %    \end{macrocode}
  1979. %    In the following loop we append for every already typeset label
  1980. %    an \verb+\hbox{\strut}+ to the definition of \verb+\@tempa+.
  1981. %    \begin{macrocode}
  1982.     \loop \ifnum\count@>\z@
  1983.       \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat
  1984. %    \end{macrocode}
  1985. %    Now be put the definition of \verb+\makelabel+ together.
  1986. % \changes{v1.5b}{89/04/27}{vbox to vtop changed in makelabel (test)}
  1987. % \changes{v1.5e}{89/04/28}{ht strutbox changed to baselineskip (test)}
  1988. %    \begin{macrocode}
  1989.     \edef\makelabel##1{\llap{\vtop to\baselineskip
  1990.                                {\@tempa\hbox{##1}\vss}}}%
  1991. %    \end{macrocode}
  1992. %    Next we increment the value of the nesting depth counter.  This
  1993. %    value inside the {\sf macro} environment is always at least one
  1994. %    after this point, but its toplevel definition is zero. Provided
  1995. %    this environment has been used correctly, $\verb+\macro@cnt+=0$
  1996. %    should not occur when $\verb+@inlabel+=\sf true$.  It is however
  1997. %    possible if this environment is used within other list
  1998. %    environments (but this would have little point).
  1999. %    \begin{macrocode}
  2000.     \advance \macro@cnt \@ne
  2001. %    \end{macrocode}
  2002. %    If \verb+@inlabel+ is false we reset \verb+\macro@cnt+ assuming
  2003. %    that there is enough room to print the macro name without
  2004. %    shifting.
  2005. %    \begin{macrocode}
  2006.   \else  \macro@cnt\@ne  \fi
  2007. %    \end{macrocode}
  2008. %    Now the label will be produced using \verb+\item+. The following
  2009. %    line is only a hack saving the day until a better solution is
  2010. %    implemented.  We have to face two problems: the argument might be
  2011. %    a \verb+\par+ which is forbidden in the argument of other macros
  2012. %    if they are not defined as \verb+\long+, or it is something like
  2013. %    \verb+\iffalse+ or \verb+\else+, i.e.\ something which will be
  2014. %    misinterpreted when \TeX{} is skipping conditional text. In both
  2015. %    cases \verb+\item+ will bomb, so we protect the argument by using
  2016. %    \verb+\string+.
  2017. %    \begin{macrocode}
  2018.   \edef\@tempa{\noexpand\item[\noexpand\PrintMacroName{\string#1}]}%
  2019.   \@tempa
  2020. %    \end{macrocode}
  2021. %    At this point we also produce an index entry.  Because it is not
  2022. %    known which index sorting program will be used, we do not use the
  2023. %    command \verb+\index+, but rather a command
  2024. %    \verb+\SpecialMainIndex+ after advancing the counter for indexing
  2025. %    by line number.  This may be redefined by the user in
  2026. %    order to generate an index entry which will be understood by the
  2027. %    index program in use (note the definition of
  2028. %    \verb+\SpecialMainIndex+ for our installation).
  2029. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2030. %    \begin{macrocode}
  2031.   {\advance\c@CodelineNo\@ne\SpecialMainIndex{#1}\nobreak}%
  2032. %    \end{macrocode}
  2033. %    The \verb+\nobreak+ is needed to prevent a page break after the
  2034. %    \verb+\write+ produced by the \verb+\SpecialMainIndex+ macro.  We
  2035. %    exclude the new macro in the cross-referencing feature, to
  2036. %    prevent spurious non-main entry references.  Regarding possibly
  2037. %    problematic arguments, the implementation takes
  2038. %    care of \verb+\par+ and the conditionals are uncritical.
  2039. %    \changes{v1.7a}{92/03/02}{Removed redundant code checking for
  2040. %                             `par.}^^A
  2041. %    \begin{macrocode}
  2042.   \DoNotIndex{#1}%
  2043. %    \end{macrocode}
  2044. %    Because the space symbol should be ignored between the
  2045. %    \verb+\begin{macro}{...}+ and the following text we must take
  2046. %    care of this with \verb+\ignorespaces+.
  2047. %    \begin{macrocode}
  2048.   \ignorespaces}
  2049. %    \end{macrocode}
  2050. % \end{macro}
  2051. % \end{macro}
  2052. % \end{macro}
  2053. % \end{macro}
  2054. % \begin{macro}{\endmacro}
  2055. %    When ending a {\sf macro} environment we have to cancel the
  2056. %    \verb+\endgroup+ generated by the \verb+\end+ macro as long as we
  2057. %    are still inside another {\sf macro} environment. Therefore
  2058. %    we check the value of the \verb+\macro@level+ counter. Of course
  2059. %    this counter also has to be decremented.
  2060. %    \SpecialIndex{\macro@cnt}
  2061. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  2062. %    \begin{macrocode}
  2063. \def\endmacro{%
  2064.    \endtrivlist
  2065.    \ifnum\macro@level>\@ne \advance\macro@level\m@ne \begingroup \fi}
  2066. %    \end{macrocode}
  2067. %  \end{macro}
  2068. % \begin{macro}{\MacroTopsep}
  2069. %    Here is the default value for the \verb+\MacroTopsep+ parameter
  2070. %    used above.
  2071. %    \begin{macrocode}
  2072. \newskip\MacroTopsep     \MacroTopsep = 7pt plus 2pt minus 2pt
  2073. %    \end{macrocode}
  2074. % \end{macro}
  2075. % \subsection{Formatting the margin}
  2076. % The following three macros should be user definable.
  2077. % Therefore we define those macros only if they have not already
  2078. % been defined.
  2079. % \begin{macro}{\PrintMacroName}
  2080. % \begin{macro}{\PrintDescribeMacro}
  2081. % \begin{macro}{\PrintDescribeEnv}
  2082. %    The formatting of the macro name in the left margin is done by
  2083. %    these macros. We first set a \verb+\strut+ to get the height and
  2084. %    depth of the normal lines. Then we change to the
  2085. %    \verb+\MacroFont+ using \verb+\string+ to \verb+\catcode+ the
  2086. %    argument to other (assuming that it is a macro name). Finally we
  2087. %    print a space.  The font change remains local since this macro
  2088. %    will be called inside an \verb+\hbox+.
  2089. %    \begin{macrocode}
  2090. \@ifundefined{PrintMacroName}
  2091.    {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{}
  2092. %    \end{macrocode}
  2093. %    We use the same formatting conventions when describing a macro.
  2094. %    \begin{macrocode}
  2095. \@ifundefined{PrintDescribeMacro}
  2096.    {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{}
  2097. %    \end{macrocode}
  2098. %    To format the name of a new environment there is no need to use
  2099. %    \verb+\string+.
  2100. %    \begin{macrocode}
  2101. \@ifundefined{PrintDescribeEnv}
  2102.    {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{}
  2103. %    \end{macrocode}
  2104. % \end{macro}
  2105. % \end{macro}
  2106. % \end{macro}
  2107. % \subsection{Creating index entries by scanning `macrocode'}
  2108. %  The following macros ensure that index entries are created for each
  2109. %  occurrence of a \TeX-like command (something starting with
  2110. %  `\verb+\+') providing indexing has been turned on with "\PageIndex"
  2111. %  or "\CodelineIndex".  With the default definitions of
  2112. %  \verb+\SpecialMainIndex+, etc., the index file generated is
  2113. %  intended to be processed by Chen's {\sf makeindex} program
  2114. %  \cite{art:Chen}.
  2115. %  Of course, in {\em this\/} style file itself we've sometimes had to
  2116. %  make \verb+|+ take the r\^ole of \TeX's escape character to
  2117. %  introduce command names at places where \verb+\+ has to belong to
  2118. %  some other category.  Therefore, we may also need to recognize
  2119. %  \verb+|+ as the introducer for a command when setting the text
  2120. %  inside the {\sf macrocode} environment.  Other users may have the
  2121. %  need to make similar reassignments for their macros.
  2122. % \begin{macro}{\SpecialEscapechar}\label{sect:specialescapechar}
  2123. % \begin{macro}{\active@escape@char}
  2124. % \begin{macro}{\special@escape@char}
  2125. %    The macro \verb+\SpecialEscapechar+ is used to denote a special
  2126. %    escape character for the next {\sf macrocode} environment. It has
  2127. %    one argument---the new escape character given as a
  2128. %    `single-letter' control sequence.  Its main purpose is defining
  2129. %    \verb+\special@escape@char+ to produce the chosen escape
  2130. %    character \verb+\catcode+$\,$d to 12 and
  2131. %    \verb+\active@escape@char+ to produce the same character but with
  2132. %    \verb+\catcode+ 13.
  2133. %    The macro \verb+\special@escape@char+ is used to {\em print\/}
  2134. %    the escape character while \verb+\active@escape@char+ is needed
  2135. %    in the definition of \verb+\init@crossref+ to start the scanning
  2136. %    mechanism.
  2137. %    In the definition of \verb+\SpecialEscapechar+ we need an
  2138. %    arbitrary character with \verb+\catcode+ 13. We use `\~{}' and
  2139. %    ensure that it is active. The \verb+\begingroup+ is used to make
  2140. %    a possible change local to the expansion of
  2141. %    \verb+\SpecialEscapechar+.
  2142. % \changes{v1.7g}{92/6/19}{Making tilde active moved outside
  2143. %    definition}
  2144. %    \begin{macrocode}
  2145. \begingroup
  2146. \catcode`\~\active
  2147. \gdef\SpecialEscapechar#1{%
  2148.     \begingroup
  2149. %    \end{macrocode}
  2150. %    Now we are ready for the definition of
  2151. %    \verb+\active@escape@char+.  It's a little tricky: we first
  2152. %    define locally the uppercase code of `\~{}' to be the new escape
  2153. %    character.
  2154. %    \begin{macrocode}
  2155.      \uccode`\~`#1%
  2156. %    \end{macrocode}
  2157. %    Around the definition of \verb+\active@escape@char+ we place an
  2158. %    \verb+\uppercase+ command. Recall that the expansion of
  2159. %    \verb+\uppercase+ changes characters according to their
  2160. %    \verb+\uccode+, but leaves their \verb+\catcode+$\,$s untouched
  2161. %    (cf.\ \TeX{}book page 41).
  2162. %    \begin{macrocode}
  2163.      \uppercase{\gdef\active@escape@char{~}}%
  2164. %    \end{macrocode}
  2165. %    The definition of \verb+\special@escape@char+ is easier, we use
  2166. %    \verb+\string+ to \verb+\catcode+ the argument of
  2167. %    \verb+\SpecialEscapechar+ to 12 and suppress the preceding
  2168. %    \verb+\escapechar+.
  2169. %    \begin{macrocode}
  2170.      \escapechar\m@ne  \xdef\special@escape@char{\string#1}%
  2171. %    \end{macrocode}
  2172. %    Now we close the group and end the definition: the value of
  2173. %    \verb+\escapechar+ as well as the \verb+\uccode+ and
  2174. %    \verb+\catcode+ of `\~{}' will be restored.
  2175. %    \begin{macrocode}
  2176.    \endgroup}
  2177. \endgroup
  2178. %    \end{macrocode}
  2179. % \end{macro}
  2180. % \end{macro}
  2181. % \end{macro}
  2182. % \begin{macro}{\init@crossref}
  2183. %    The replacement text of \verb+\init@crossref+ should fulfill the
  2184. %    following tasks:
  2185. %    \begin{itemize}
  2186. %       \parindent4em
  2187. %       \item[1)]
  2188. %          \verb+\catcode+ all characters used in macro names to
  2189. %          11 (i.e.\ `letter').
  2190. %       \item[2)]
  2191. %          \verb+\catcode+ the `\verb+\+' character to 13
  2192. %          (i.e.\ `active').
  2193. %       \item[3a)]
  2194. %          \verb+\let+ the `\verb+\+' equal \verb+\scan@macro+
  2195. %          (i.e.\ start the macro scanning mechanism) if there is
  2196. %          no  special escape character (i.e.\ the
  2197. %          \verb+\special@escape@char+ is `\verb+\+').
  2198. %       \item[3b)]
  2199. %          Otherwise \verb+\let+ it equal \verb+\bslash+, i.e.\
  2200. %          produce a printable \verb+\+.
  2201. %       \item[4)]
  2202. %          Make the \meta{special escape character} active.
  2203. %       \item[5)]
  2204. %          \verb+\let+ the active version of the special escape
  2205. %          character
  2206. %          (i.e.\ the expansion of \verb+\active@escape@char+) equal
  2207. %          \verb+\scan@macro+.
  2208. %    \end{itemize}
  2209. %    The reader might ask why we bother to \verb+\catcode+ the
  2210. %    `\verb+\+' first to 12 (at the end of \verb+\macro@code+) then
  2211. %    re-\verb+\catcode+ it to 13 in order to produce a $\verb+\+_{12}$
  2212. %    in case 3b) above.  This is done because we have to ensure that
  2213. %    `\verb+\+' has \verb+\catcode+ 13 within the {\sf macrocode}
  2214. %    environment.  Otherwise the delimiter for the argument of
  2215. %    \verb+\xmacro@code+ would not be found (parameter matching
  2216. %    depends on \verb+\catcode+$\,$s).
  2217. %    Therefore we first re-\verb+\catcode+ some characters.
  2218. %    \begin{macrocode}
  2219. \begingroup   \catcode`\|=\z@  \catcode`\\=\active
  2220. %    \end{macrocode}
  2221. %    We carry out tasks 2) and 3b) first.
  2222. %    \SpecialEscapechar{\|}
  2223. %    \begin{macrocode}
  2224. |gdef|init@crossref{|catcode`|\|active   |let\|bslash
  2225. %    \end{macrocode}
  2226. %    Because of the popularity of the `\verb+@+' character as a
  2227. %    `letter' in macros, we normally have to change its
  2228. %    \verb+\catcode+ here, and thus fulfill task 1).  But the macro
  2229. %    designer might use other characters as private letters as well,
  2230. %    so we use a macro to do the \verb+\catcode+ switching.
  2231. %    \SpecialEscapechar\|
  2232. %    \begin{macrocode}
  2233.     |MakePrivateLetters
  2234. %    \end{macrocode}
  2235. %    Now we \verb+\catcode+ the special escape character to 13 and
  2236. %    \verb+\let+ it equal \verb+\scan@macro+, i.e.\ fulfill tasks 4)
  2237. %    and 5). Note the use of \verb+\expandafter+ to insert the chosen
  2238. %    escape character saved in \verb+\special@escape@char+ and
  2239. %    \verb+\active@escape@char+.
  2240. %    \SpecialEscapechar\|
  2241. %    \begin{macrocode}
  2242.     |catcode|expandafter`|special@escape@char|active
  2243.     |expandafter|let|active@escape@char|scan@macro}
  2244. |endgroup
  2245. %    \end{macrocode}
  2246. %    If there is no special escape character, i.e.\ if
  2247. %    \verb+\SpecialEscapechar+ is \verb+\\+, the second last line will
  2248. %    overwrite the previous definition of $\verb+\+_{13}$.  In this
  2249. %    way all tasks are fulfilled.
  2250. %    For happy documenting we give default values to
  2251. %    \verb+\special@escape@char+ and \verb+\active@escape@char+ with
  2252. %    the following line:
  2253. %    \begin{macrocode}
  2254. \SpecialEscapechar{\\}
  2255. %    \end{macrocode}
  2256. % \end{macro}
  2257. % \begin{macro}{\MakePrivateLetters}
  2258. %    Here is the default definition of this command, which makes just
  2259. %    the \verb+@+ into a letter. The user may change it if he/she
  2260. %    needs more or other characters masquerading as letters.
  2261. %    \begin{macrocode}
  2262. \@ifundefined{MakePrivateLetters}
  2263.     {\let\MakePrivateLetters\makeatletter}{}
  2264. %    \end{macrocode}
  2265. % \end{macro}
  2266. % \begin{macro}{\close@crossref}
  2267. %    At the end of a cross-referencing part we prepare ourselves for
  2268. %    the next one by setting the escape character to `\verb+\+'.
  2269. %    \begin{macrocode}
  2270. \def\close@crossref{\SpecialEscapechar\\}
  2271. %    \end{macrocode}
  2272. % \end{macro}
  2273. % \subsection{Macros for scanning macro names}
  2274. % \begin{macro}{\scan@macro}
  2275. % \changes{v1.5k}{89/09/04}{Support for checksum added.}
  2276. % \begin{macro}{\macro@namepart}
  2277. %    The \verb+\init@crossref+ will have made \verb+\active+ our
  2278. %    \verb+\special@escape@char+, so that each
  2279. %    \verb+\active@escape@char+ will invoke \verb+\scan@macro+ when
  2280. %    within the {\sf macrocode} environment.  By this means, we can
  2281. %    automatically add index entries for every \TeX-like command which
  2282. %    is met whilst setting (in verbatim) the contents of {\sf
  2283. %    macrocode} environments.
  2284. %    \begin{macrocode}
  2285. \def\scan@macro{%
  2286. %    \end{macrocode}
  2287. %    First we output the character which triggered this macro.  Its
  2288. %    version \verb+\catcode+$\,$d to 12 is saved in
  2289. %    \verb+\special@escape@char+. We also call \verb+\step@checksum+
  2290. %    to generate later on a proper check-sum (see section
  2291. %    \ref{sec:checksum} for details).
  2292. %    \begin{macrocode}
  2293.    \special@escape@char
  2294.    \step@checksum
  2295. %    \end{macrocode}
  2296. %    If the {\sf macrocode} environment contains, for example, the
  2297. %    command \verb+\\+, the second \verb+\+ should not start the
  2298. %    scanning mechanism. Therefore we use a switch to decide if
  2299. %    scanning of macro names is allowed.
  2300. %    \begin{macrocode}
  2301.    \ifscan@allowed
  2302. %    \end{macrocode}
  2303. %    The macro assembles the letters forming a \TeX\ command in
  2304. %    \verb+\macro@namepart+ so this is initially cleared; we then set
  2305. %    \verb+\next+ to the {\it first\/} character following the
  2306. %    \verb+\+ and call \verb+\macro@switch+ to determine whether that
  2307. %    character is a letter or not.
  2308. %    \begin{macrocode}
  2309.       \let\macro@namepart\@empty
  2310.       \def\next{\futurelet\next\macro@switch}%
  2311. %    \end{macrocode}
  2312. %    As you recognize, we actually did something else, because we have
  2313. %    to defer the \verb+\futurelet+ call until after the final
  2314. %    \verb+\fi+.  If, on the other hand, the scanning is disabled we
  2315. %    simply \verb+\let+ \verb+\next+ equal `empty'.
  2316. %    \begin{macrocode}
  2317.    \else \let\next\@empty \fi
  2318. %    \end{macrocode}
  2319. %    Now we invoke \verb+\next+ to carry out what's needed.
  2320. %    \begin{macrocode}
  2321.    \next}
  2322. %    \end{macrocode}
  2323. % \end{macro}
  2324. % \end{macro}
  2325. % \begin{macro}{\ifscan@allowed}
  2326. % \begin{macro}{\scan@allowedtrue}
  2327. % \begin{macro}{\scan@allowedfalse}
  2328. %    \verb+\ifscan@allowed+ is the switch used above to determine if
  2329. %    the \verb+\active@escape@char+\SpecialIndex{\active@escape@char}
  2330. %    should start the macro scanning mechanism.
  2331. %    \begin{macrocode}
  2332. \newif\ifscan@allowed    \scan@allowedtrue
  2333. %    \end{macrocode}
  2334. % \end{macro}
  2335. % \end{macro}
  2336. % \end{macro}
  2337. % \begin{macro}{\EnableCrossrefs}
  2338. % \begin{macro}{\DisableCrossrefs}
  2339. %    At this point we might define two macros which allow the user to
  2340. %    disable or enable the cross-referencing mechanism. Processing of
  2341. %    files will be faster if only main index entries are generated
  2342. %    (i.e., if \verb+\DisableCrossrefs+ is in force).
  2343. %    \begin{macrocode}
  2344. \def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack}
  2345. %    \end{macrocode}
  2346. %    The macro \verb+\EnableCrossrefs+ will also disable any
  2347. %    \verb+\DisableCrossrefs+ command encountered afterwards.
  2348. %    \begin{macrocode}
  2349. \def\EnableCrossrefs{\@bsphack\scan@allowedtrue
  2350.                      \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack}
  2351. %    \end{macrocode}
  2352. % \end{macro}
  2353. % \end{macro}
  2354. % \begin{macro}{\macro@switch}
  2355. %    Now that we have the character which follows the escape character
  2356. %    (in \verb+\next+), we can determine whether it's a `letter'
  2357. %    (which probably includes \verb+@+).
  2358. %    If it is, we let \verb+\next+ invoke a macro which assembles the
  2359. %    full command name.
  2360. %    \begin{macrocode}
  2361. \def\macro@switch{\ifcat\noexpand\next a%
  2362.      \let\next\macro@name
  2363. %    \end{macrocode}
  2364. %    Otherwise, we have a `single-character' command name.  For all
  2365. %    those single-character names, we use \verb+\short@macro+ to
  2366. %    process them into suitable index entries.
  2367. %    \begin{macrocode}
  2368.      \else \let\next\short@macro  \fi
  2369. %    \end{macrocode}
  2370. %    Now that we know what macro to use to process the macro name, we
  2371. %    invoke it~\ldots
  2372. %    \begin{macrocode}
  2373.    \next}
  2374. %    \end{macrocode}
  2375. % \end{macro}
  2376. % \begin{macro}{\short@macro}
  2377. % \changes{v1.5c}{89/4/27}{Corrected bad bug by putting the
  2378. %                         scan@allowedfalse macro before printing
  2379. %                         the argument.}
  2380. % \changes{v1.7a}{92/03/10}{Ensure character stored in `macro@namepart
  2381. %                           as `letter' so index exclusion works.}
  2382. %    This macro will be invoked (with a single character as parameter)
  2383. %    when a single-character macro name has been spotted whilst
  2384. %    scanning within the {\sf macrocode} environment.
  2385. %    First we take a look at the \verb+\index@excludelist+ to see
  2386. %    whether this macro name should produce an index entry.  This is
  2387. %    done by the \verb+\ifnot@excluded+ macro which assumes that the
  2388. %    macro name is saved in \verb+\macro@namepart+.  The character
  2389. %    mustn't be stored with a special category code or exclusion from
  2390. %    the index won't work, so we employ the case-changing trick used
  2391. %    elsewhere.  Since the argument might be an active character,
  2392. %    \verb+\string+ is used to normalize it. 
  2393. %    \begin{macrocode}
  2394. \def\short@macro#1{\begingroup
  2395.    \catcode`\&=11  \uccode`\&=\expandafter`\string#1%
  2396.    \uppercase{\def\macro@namepart{&}}%
  2397.    \endgroup
  2398.    \ifnot@excluded
  2399. %    \end{macrocode}
  2400. %    If necessary the index entry is produced by the macro
  2401. %    \verb+\produce@index+. Depending on the actual character seen,
  2402. %    this macro has to do different things, so we pass the character
  2403. %    as an argument.
  2404. %    \begin{macrocode}
  2405.      \produce@index{#1}\fi
  2406. %    \end{macrocode}
  2407. %    Then we disable the cross-referencing mechanism with
  2408. %    \verb+\scan@allowedfalse+ and print the actual character. The
  2409. %    index entry was generated first to ensure that no page break
  2410. %    intervenes (recall that a \verb+^^M+ will start a new line).
  2411. %    \begin{macrocode}
  2412.     \scan@allowedfalse#1%
  2413. %    \end{macrocode}
  2414. %    After typesetting the character we can safely enable the
  2415. %    cross-referencing feature again. Note that this macro won't be
  2416. %    called (since \verb+\macro@switch+ won't be called) if
  2417. %    cross-referencing is globally disabled.
  2418. %    \begin{macrocode}
  2419.     \scan@allowedtrue }
  2420. %    \end{macrocode}
  2421. % \end{macro}
  2422. % \begin{macro}{\produce@index}
  2423. % \changes{v1.4s}{89/04/23}{Added noexpand to all {\tt\protect\bslash
  2424. %                if} tests
  2425. %               to avoid garbage produced by new active chars}
  2426. % \changes{v1.4s}{89/04/23}{Used {\tt\protect\bslash string} for the
  2427. %                          same reason.}
  2428. % \changes{v1.5c}{89/4/27}{Corrected bad bug by placing the
  2429. %                         scan@allowedfalse macro into short@macro}
  2430. %    This macro is supposed to generate a suitable \verb+\SortIndex+
  2431. %    command for a given single-letter control sequence.  We test
  2432. %    first for the cases which involve active characters (i.e.\ the
  2433. %    backslash, the special escape character (if any), the space and
  2434. %    the \verb+^^M+).  Using the \verb+\if+ test (testing for
  2435. %    character codes), we have to ensure that the argument isn't
  2436. %    expanded.
  2437. %    \begin{macrocode}
  2438. \def\produce@index#1{%
  2439.   \if\noexpand#1\special@escape@char
  2440. %    \end{macrocode}
  2441. %    If the character is the special escape character (or the
  2442. %    `\verb+\+' in case there was none) the \verb+\it@is@a+ macro is
  2443. %    used to produce the actual \verb+\SortIndex+ call.
  2444. %    \begin{macrocode}
  2445.      \scan@allowedfalse \it@is@a\special@escape@char \else
  2446. %    \end{macrocode}
  2447. %    Next comes the test for a `\verb+\+' which must be the
  2448. %    $\verb+\+_{13}$ expanding to \verb+\bslash+.
  2449. %    \begin{macrocode}
  2450.      \if\noexpand#1\bslash \it@is@a\bslash \else
  2451. %    \end{macrocode}
  2452. %    Another possibility is \verb*+ +$_{13}$. Recall that \verb+\space+
  2453. %    produces a \verb*+ +$_{10}$.
  2454. %    \begin{macrocode}
  2455.        \if\noexpand#1\space \it@is@a\space \else
  2456. %    \end{macrocode}
  2457. %    The last\footnote{Well, it isn't the last active character after
  2458. %                      all. I added {\tt \bslash @noligs} some days ago
  2459. %                      and now {\tt `} too is active. So we have to make
  2460. %                      sure that such characters don't get expanded in 
  2461. %                      the index.} 
  2462. %    possibility of an active character is \verb+^^M+\@.  In this case
  2463. %    we don't test for character codes, since it is easier to look if
  2464. %    the character is equal to \verb+\par+. (We are inside the {\sf
  2465. %    macrocode} environment.)
  2466. %    \begin{macrocode}
  2467.          \ifx#1\par
  2468. %    \end{macrocode}
  2469. %    If we end up here we have just scanned a \verb+\^^M+ or something
  2470. %    similar. Since this will be treated like \verb*+\ + by \TeX{} we
  2471. %    produce a corresponding index entry.
  2472. %    \begin{macrocode}
  2473.          \it@is@a\space \else
  2474. %    \end{macrocode}
  2475. %    If it is the token \verb+\relax+ we do nothing. This can't happen
  2476. %    when the `doc' option is used in the way described here, but was
  2477. %    added to allow extensions like the {\tt idxverb} option.
  2478. %  \changes{v1.5t}{89/11/14}{Added `relax as a possible token to allow
  2479. %                            extensions.}
  2480. %    \begin{macrocode}
  2481.          \ifx#1\relax \else
  2482. %    \end{macrocode}
  2483. %    The next three branches are needed because of bugs in
  2484. %    our {\sf makeindex} program. You can't produce unbalanced index
  2485. %    entries\footnote{This is possible for \TeX{} if you use
  2486. %                     {\tt\string{$_{12}$ \rm or \tt\string}$_{12}$},
  2487. %                     but {\sf makeindex} will complain.}
  2488. %    and you have to double a percent character. To get around these
  2489. %    restrictions we use special macros to produce the \verb+\index+
  2490. %    calls.\footnote{Brian {\sc Hamilton Kelly} has written fixes for
  2491. %                  all three
  2492. %                  bugs. When they've found their way through all
  2493. %                    installations,
  2494. %                    the lines above will be removed. See 
  2495. %                    page~\pageref{bug:fixes} if you already have them.
  2496. %                    (I'm not sure which versions incorporate these, but
  2497. %                    2.11 is OK.  See also
  2498. %                    \pageref{makeindex:version}.)}
  2499. %    \begin{macrocode}
  2500.            \if\noexpand#1\bgroup \LeftBraceIndex \else
  2501.              \if\noexpand#1\egroup \RightBraceIndex \else
  2502.                \if\noexpand#1\percentchar \PercentIndex \else
  2503. %    \end{macrocode}
  2504. %    All remaining characters are used directly to produce their index
  2505. %    entries. This is possible even for the characters which have
  2506. %    special meanings in the index program, provided we quote the
  2507. %    characters.  (This is correctly done in \verb+\it@is@a+.)
  2508. %    \begin{macrocode}
  2509.                  \it@is@a{\string#1}%
  2510. %    \end{macrocode}
  2511. %    We now need a whole pile of \verb+\fi+$\,$s to match up with
  2512. %    the \verb+\if+$\,$s.
  2513. %    \begin{macrocode}
  2514.        \fi \fi \fi \fi \fi \fi \fi \fi}
  2515. %    \end{macrocode}
  2516. % \end{macro}
  2517. % \begin{macro}{\macro@name}
  2518. %    We now come to the macro which assembles command names which
  2519. %    consist of one or more `letters' (which might well include
  2520. %    \verb+@+ symbols, or anything else which has a \verb+\catcode+ of
  2521. %    11).
  2522. %    To do this we add the `letter' to the existing definition of
  2523. %    \verb+\macro@namepart+ (which you will recall was originally set
  2524. %    to \verb+\@empty+).
  2525. %    \begin{macrocode}
  2526. \def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}%
  2527. %    \end{macrocode}
  2528. %    Then we grab hold of the {\em next\/} single character and let
  2529. %    \verb+\more@macroname+ determine whether it belongs to the letter
  2530. %    string forming the command name or is a `non-letter'.
  2531. %    \begin{macrocode}
  2532.      \futurelet\next\more@macroname}
  2533. %    \end{macrocode}
  2534. % \end{macro}
  2535. % \begin{macro}{\more@macroname}
  2536. %    This causes another call of \verb+\macro@name+ to add in the next
  2537. %    character, if it is indeed a `letter'.
  2538. %    \begin{macrocode}
  2539. \def\more@macroname{\ifcat\noexpand\next a%
  2540.      \let\next\macro@name
  2541. %    \end{macrocode}
  2542. %    Otherwise, it finishes off the index entry by invoking
  2543. %    \verb+\macro@finish+.
  2544. %    \begin{macrocode}
  2545.      \else \let\next\macro@finish \fi
  2546. %    \end{macrocode}
  2547. %    Here's where we invoke whatever macro was \verb+\let+ equal to
  2548. %    \verb+\next+.
  2549. %    \begin{macrocode}
  2550.      \next}
  2551. %    \end{macrocode}
  2552. % \end{macro}
  2553. % \begin{macro}{\macro@finish}
  2554. %    When we've assembled the full `letter'-string which forms the
  2555. %    command name, we set the characters forming the entire command
  2556. %    name, and generate an appropriate \verb+\index+ command (provided
  2557. %    the command name is not on the list of exclusions).  The
  2558. %    `\verb+\+' is already typeset; therefore we only have to output
  2559. %    all `letters' saved in \verb+\macro@namepart+.
  2560. %    \begin{macrocode}
  2561. \def\macro@finish{%
  2562.   \macro@namepart
  2563. %    \end{macrocode}
  2564. %    Then we call \verb+\ifnot@excluded+ to decide whether we have to
  2565. %    produce an index entry. The construction with \verb+\@tempa+ is
  2566. %    needed because we want the expansion of \verb+\macro@namepart+ in
  2567. %    the \verb+\index+ command.\footnote{The {\tt \bslash index}
  2568. %    command will expand its argument in the {\tt\bslash output}
  2569. %    routine.  At this time {\tt\bslash macro@namepart} might have a
  2570. %    new value.}
  2571. %    \begin{macrocode}
  2572.   \ifnot@excluded
  2573.      \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
  2574.      \@tempa  \fi}
  2575. %    \end{macrocode}
  2576. % \end{macro}
  2577. % \subsection[The index exclude list]{The index exclude
  2578. %             list\footnotemark} 
  2579. %            \footnotetext{Warning: the incomplete commentary on {\tt
  2580. %                          \bslash DoNotIndex} and the macros it calls
  2581. %                          was written by Dave Love.} 
  2582. %    The internal form of the index exclude list is
  2583. % \begin{quote}
  2584. % \meta{macro name}\verb+,+\meta{macro name}\verb+,+
  2585. % \ldots\verb+,+
  2586. % \end{quote}
  2587. % where \meta{macro name} is a macro name like
  2588. % $"\"_{12}"p"{_{11}}"@"_{11}$ or $"\"_{12}"$"_{11}$.  Note that the "\"
  2589. % has category `other' and the other characters in the name are all
  2590. % `letter', regardless of their normal category. 
  2591. % \begin{macro}{\DoNotIndex}
  2592. %    This macro is used to suppress macro names in the index.  It
  2593. %    starts off with a new group because we have to change the
  2594. %    \verb+\catcode+$\,$s of all characters which belong to `letters'
  2595. %    while macros are defined.
  2596. %    \begin{macrocode}
  2597. \def\DoNotIndex{\begingroup \MakePrivateLetters
  2598.     \catcode`\\12
  2599. %    \end{macrocode}
  2600. %    Then we call the macro which actually reads the argument given by
  2601. %    the user.
  2602. %    \begin{macrocode}
  2603.     \do@not@index}
  2604. %    \end{macrocode}
  2605. % \end{macro}
  2606. % \begin{macro}{\do@not@index}
  2607. %    We make the \verb+\do@not@index+ macro \verb+\long+
  2608. %    since the user might want to exclude the \verb+\par+ 
  2609. %    macro.
  2610. %    \begin{macrocode}
  2611. \long\def\do@not@index#1{%
  2612. %    \end{macrocode}
  2613. %    It just adds to a token list after finishing the group in which
  2614. %    the catcodes were changed.
  2615. %    \changes{v1.7a}{92/02/26}{Replaced with newdoc version.}
  2616. %    \begin{macrocode}
  2617.     \endgroup
  2618.     \addto@hook\index@excludelist{#1,}}    
  2619. %    \end{macrocode}
  2620. % \end{macro}
  2621. % \begin{macro}{\addto@hook}
  2622. % The code for adding tokens (the second argument) to a token list
  2623. % (the first argument) is taken from~\cite{art:verbatim}, but it needs
  2624. % to be "\long" in case "\par" is amongst the tokens.
  2625. %    \begin{macrocode}
  2626. \long\def\addto@hook#1#2{#1\expandafter{\the#1#2}}
  2627. %    \end{macrocode}
  2628. % \end{macro}
  2629. % \begin{macro}{\index@excludelist}
  2630. % We need an initially-empty register for the excluded list.
  2631. %    \begin{macrocode}
  2632. \newtoks\index@excludelist
  2633. \index@excludelist{}
  2634. %    \end{macrocode}
  2635. % \end{macro}
  2636. % \begin{macro}{\ifnot@excluded}
  2637. %    \changes{v1.7a}{92/02/26}{Replaced with newdoc version.}
  2638. % \begin{macro}{\expanded@notin}
  2639. %    Now we take a look at the \verb+\index@excludelist+ to see
  2640. %    whether a macro name saved in \verb+\macro@namepart+ should
  2641. %    produce an index entry. This macro is a pseudo \verb+\if+; it
  2642. %    should expand to \verb+\iftrue+ or \verb+\iffalse+ depending on
  2643. %    the contents of \verb+\index@excludelist+.
  2644. %    \begin{macrocode}
  2645. \begingroup
  2646. %    \end{macrocode}
  2647. %    First we change "\catcode"s so that "\" is `other' and "|" a
  2648. %    temporary for the escape character. This is necessary since our
  2649. %    macro names are stored that way in the "\index@excludelist".
  2650. %    \begin{macrocode}
  2651. \catcode`\|=0%
  2652. \catcode`\\=12
  2653. %    \end{macrocode}
  2654. %    Then we define "\ifnot@excluded" to call "\expanded@notin" with
  2655. %    two arguments: the first is the string "\" followed by the
  2656. %    contents of "\macro@namepart" followed by a "," and the second is
  2657. %    "\the" followed by "\index@excludelist". To achieve the expansion
  2658. %    of "\macro@namepart", i.e.\ to pass its contents, we need a
  2659. %    suitable number of "\expandafter"s.
  2660. %    \SpecialEscapechar{\|}
  2661. %    \begin{macrocode}
  2662. |gdef|ifnot@excluded{|expandafter
  2663.      |expanded@notin|expandafter{|expandafter
  2664.      \|macro@namepart,}{|the|index@excludelist}}
  2665. |endgroup
  2666. %    \end{macrocode}
  2667. %    The macro "\expanded@notin" now does the dirty work. It first
  2668. %    defines a macro "\in@@" with a very special parameter text. If
  2669. %    you look closely "\in@@" has three arguments, the first one is
  2670. %    delimited by the first argument of "\expanded@notin" (i.e.\ by
  2671. %    the string starting with a "\" and ending with a "," above), the
  2672. %    second is undelimited (which means that it will get the next
  2673. %    token after our string, and the third is delimited again and will
  2674. %    get the rest up to the token "\in@@". In other words the token
  2675. %    "\in@@" is also used as a delimiter.
  2676. %    \begin{macrocode}
  2677. \def\expanded@notin#1#2{%
  2678.  \def\in@@##1#1##2##3\in@@{%
  2679. %    \end{macrocode}
  2680. %    Now the replacement text simply compares the second argument
  2681. %    (i.e.\ the undelimited one after our string) to the token
  2682. %    "\expanded@notin". This is an unclosed "\ifx" statement which
  2683. %    means that this macro behaves similar to a normal \TeX{}
  2684. %    conditional.
  2685. %    \begin{macrocode}
  2686.   \ifx\expanded@notin##2}%
  2687. %    \end{macrocode}
  2688. %    After all these preparations we call "\in@@". First we expand the
  2689. %    token after "\in@@" (which is "\the" from the second argument to
  2690. %    "\expanded@notin"). As a result we get the contents of the
  2691. %    "\index@excludelist" inserted after "\in@@". After this contents
  2692. %    we add once more the string we are looking for, then the token
  2693. %    "\expanded@notin" and finally the token "\in@@".
  2694. %    \begin{macrocode}
  2695.  \expandafter\in@@#2#1\expanded@notin\in@@}
  2696. %    \end{macrocode}
  2697. %    Now what happens when the macro "\in@@" above gets called? The
  2698. %    first argument to "\in@@" is delimited by our string. In other
  2699. %    words it will get everything from the contents of
  2700. %    "\index@excludelist" before this string. If the string is not in
  2701. %    "\index@excludelist" then it gets the whole contents, since after
  2702. %    it we had inserted the string one more. In this case the next
  2703. %    token is "\expanded@notin" which gets assigned to the second
  2704. %    argument and the third argument will be empty. If, on the other
  2705. %    hand, the string was inside "\index@excludelist" then the second
  2706. %    argument will not be the token "\expanded@notin" and the third
  2707. %    argument will be all the garbage up to "\in@@". Therefore testing
  2708. %    the seconded argument, as done in the definition of "\in@@" will
  2709. %    tell us  whether or not the string is in "\index@includelist" and
  2710. %    this was exactly what we wanted. (Deep breath.) You got
  2711. %    that?\footnote{\TeX{}book page 125. The code described above is
  2712. %    originally due to Michael Spivak who used a similar method within
  2713. %    the \AmSTeX{} macros.}
  2714. % \end{macro}
  2715. % \end{macro}
  2716. % \subsection{Macros for generating index entries}
  2717. % Here we provide default definitions for the macros invoked to create
  2718. % index entries; these are either invoked explicitly, or automatically
  2719. % by \verb+\scan@macro+.  As already mentioned, the definitions given
  2720. % here presuppose that the \verb+.idx+ file will be processed by
  2721. % Chen's {\sf makeindex} program --- they may be redefined for use
  2722. % with the user's favourite such program.
  2723. % To assist the reader in locating items in the index, all such
  2724. % entries are sorted alphabetically {\em ignoring\/} the initial
  2725. % `\verb+\+'; this is achieved by issuing an \verb+\index+ command
  2726. % which contains the `actual' operator for {\sf makeindex}.  The
  2727. % default value for the latter operator is `\verb+@+', but the latter
  2728. % character is so popular in \LaTeX\ style files that it is necessary
  2729. % to substitute another character.  This is indicated to {\sf
  2730. % makeindex} by means of an `index style file'; the character selected
  2731. % for this function is \verb+=+, and therefore this character too must
  2732. % be specially treated when it is met in a \TeX\ command.  A suitable
  2733. % index style file is provided amongst the supporting files for this
  2734. % style file in {\tt gind.ist} and is generated from this source by
  2735. % processing with {\tt docstrip} to extract the module {\bf gind}.  A
  2736. % similar style file {\tt gglo.ist} is supplied for sorting the change
  2737. % information in the glossary file and is extracted as module {\bf
  2738. % gglo}.  First of all we add some information to the front of the
  2739. % {\tt .ist} files.  \changes{v1.7a}{92/03/11}{Gglo.ist and gind.ist
  2740. % now derivable from doc.doc with docstrip.}
  2741. %    \begin{macrocode}
  2742. %</style>
  2743. %<+gind|gglo>%% This is a MAKEINDEX style file which should be used to
  2744. %<+gind>%% generate the formatted index for use with the doc
  2745. %<+gglo>%% generate the formatted change history for use with the doc
  2746. %<+gind|gglo>%% style option. The TeX commands used below are defined in
  2747. %<+gind|gglo>%% doc.sty.  The commands for MAKEINDEX like `level'
  2748. %<+gind|gglo>%% `item_x1' are described in `` Makeindex, A General
  2749. %<+gind|gglo>%% Purpose, Formatter-Independent Index Processor'' by
  2750. %<+gind|gglo>%% Pehong Chen. 
  2751. %<+gind|gglo>
  2752. %    \end{macrocode}
  2753. % \begin{macro}{\actualchar}
  2754. % \begin{macro}{\quotechar}
  2755. % \begin{macro}{\levelchar}
  2756. %    First come the definitions of \verb+\actualchar+,
  2757. %    \verb+\quotechar+ and \verb+\levelchar+. Note, that our defaults
  2758. %    are not the ones used by the {\sf makeindex} program without a
  2759. %    style file.
  2760. %    \begin{macrocode}
  2761. %<*style>
  2762. \@ifundefined{actualchar}{\def\actualchar{=}}{}
  2763. \@ifundefined{quotechar}{\def\quotechar{!}}{}
  2764. \@ifundefined{levelchar}{\def\levelchar{>}}{}
  2765. %</style>
  2766. %<+gind|gglo>actual '='
  2767. %<+gind|gglo>quote '!'
  2768. %<+gind|gglo>level '>'
  2769. %<*style>
  2770. %    \end{macrocode}
  2771. % \end{macro}
  2772. % \end{macro}
  2773. % \end{macro}
  2774. % \begin{macro}{\encapchar}
  2775. %    The {\sf makeindex} default for the \verb+\encapchar+ isn't
  2776. %    changed.
  2777. %    \begin{macrocode}
  2778. \@ifundefined{encapchar}{\def\encapchar{|}}{}
  2779. %    \end{macrocode}
  2780. % \end{macro}
  2781. % \begin{macro}{\verbatimchar}
  2782. %    We also need a special character to be used as a delimiter for
  2783. %    the \verb+\verb*+ command used in the definitions below.
  2784. %    \begin{macrocode}
  2785. \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
  2786. %    \end{macrocode}
  2787. % \end{macro}
  2788. % \begin{macro}{\SpecialIndex}
  2789. %    The \verb+\SpecialIndex+ command creates index entries for
  2790. %    macros.  If the argument is \verb+\+$xyz$, the command produces
  2791. %    \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}|
  2792. %    given the above defined defaults for \verb+\actualchar+,
  2793. %    \verb+\quotechar+ and \verb+\verbatimchar+.  We first remove the
  2794. %    initial `\verb+\+' to get a better index.
  2795. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2796. %    \begin{macrocode}
  2797. \def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble
  2798.                                       \string#1\actualchar
  2799. %    \end{macrocode}
  2800. %    Then follows the actual entry. A \verb+\quotechar+ is placed
  2801. %    before the \verb+*+ to allow its use as a special {\sf makeindex}
  2802. %    character.  Again \verb+\@bsphack+ and \verb+\@esphack+ are used
  2803. %    to make the macros invisible.
  2804. %    \begin{macrocode}
  2805.       \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}%
  2806.     \@esphack}
  2807. %    \end{macrocode}
  2808. % \end{macro}
  2809. % \begin{macro}{\SpecialMainIndex}
  2810. % \begin{macro}{\SpecialUsageIndex}
  2811. %    The \verb+\SpecialMainIndex+ macro is used to cross-reference the
  2812. %    names introduced by the {\sf macro} environment.  The action is
  2813. %    as for \verb+\SpecialIndex+, except that {\sf makeindex} is
  2814. %    instructed to `encap'sulate the entry with the string
  2815. %    \verb+|main+ to cause it to generate a call of the \verb+\main+
  2816. %    macro.
  2817. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2818. %    \begin{macrocode}
  2819. \def\SpecialMainIndex#1{\@bsphack\special@index{\expandafter\@gobble
  2820.                                         \string#1\actualchar
  2821.                                         \string\verb
  2822.                                         \quotechar*\verbatimchar
  2823.                                         \string#1\verbatimchar
  2824.                                         \encapchar main}%
  2825.                         \@esphack}
  2826. %    \end{macrocode}
  2827. %    The \verb+\SpecialUsageIndex+ is literally the same---only we use
  2828. %    {\tt usage} instead of {\tt main}.
  2829. %    \begin{macrocode}
  2830. \def\SpecialUsageIndex#1{\@bsphack\index{\expandafter\@gobble\string#1%
  2831.     \actualchar\string\verb\quotechar*\verbatimchar
  2832.     \string#1\verbatimchar
  2833.     \encapchar usage}\@esphack}
  2834. %    \end{macrocode}
  2835. % \end{macro}
  2836. % \end{macro}
  2837. % \begin{macro}{\SpecialEnvIndex}
  2838. %    Indexing environments is done a little bit differently; we produce
  2839. %    two index entries with the \verb+\SpecialEnvIndex+ macro:
  2840. %    \begin{macrocode}
  2841. \def\SpecialEnvIndex#1{\@bsphack
  2842. %    \end{macrocode}
  2843. %    First we sort the environment under its own name stating in the
  2844. %    actual entry that this is an environment.
  2845. %    \begin{macrocode}
  2846.     \index{#1\actualchar{\tt #1} (environment)\encapchar usage}%
  2847. %    \end{macrocode}
  2848. %    The second entry is sorted as a subitem under the key
  2849. %    `environments:'. 
  2850. %    \begin{macrocode}
  2851.     \index{environments:\levelchar{\tt #1}\encapchar usage}\@esphack}
  2852. %    \end{macrocode}
  2853. %    Because both entries correspond to `descriptions' of the
  2854. %    environment, we encapsulate the page numbers with the
  2855. %    \verb+\usage+ macro.
  2856. % \end{macro}
  2857. % \begin{macro}{\SortIndex}
  2858. %    This macro is used to generate the index entries for any
  2859. %    single-character command that \verb+\scan@macro+ encounters.  The
  2860. %    first parameter specifies the lexical order for the character,
  2861. %    whilst the second gives the actual characters to be printed in
  2862. %    the entry. It can also be used directly to generate index entries
  2863. %    which differ in sort key and actual entry.
  2864. %    \begin{macrocode}
  2865. \def\SortIndex#1#2{\index{#1\actualchar#2}}
  2866. %    \end{macrocode}
  2867. % \end{macro}
  2868. % \begin{macro}{\it@is@a}
  2869. %    This macro is supposed to produce a correct \verb+\SortIndex+
  2870. %    entry for a given character. Since this character might be
  2871. %    recognised as a `command' character by the index program used,
  2872. %    all characters are quoted with the \verb+\quotechar+.
  2873. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2874. %    \begin{macrocode}
  2875. \def\it@is@a#1{\special@index{\quotechar #1\actualchar
  2876.                           \string\verb\quotechar*\verbatimchar
  2877.                           \quotechar\bslash\quotechar#1\verbatimchar}}
  2878. %    \end{macrocode}
  2879. % \end{macro}
  2880. % \begin{macro}{\LeftBraceIndex}
  2881. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2882. % \begin{macro}{\RightBraceIndex}
  2883. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2884. %    These two macros fix the problems with {\sf makeindex}.  Note the
  2885. %    `hack' with \verb+\iffalse}\fi+ to satisfy both \TeX{} and the
  2886. %    {\sf makeindex} program. When this is written to the {\tt .idx}
  2887. %    file \TeX{} will see both braces (so we get a balanced text).
  2888. %    {\sf makeindex} will also see balanced braces but when the actual
  2889. %    index entry is again processed by \TeX{} the brace in between
  2890. %    \verb+\iffalse+ \verb+\fi+ will vanish.
  2891. %    \begin{macrocode}
  2892. \@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{%
  2893.    \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar
  2894.           \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{}
  2895. \@ifundefined{RightBraceIndex}{\def\RightBraceIndex{%
  2896.  \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb
  2897.            \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{}
  2898. %    \end{macrocode}
  2899. % \end{macro}
  2900. % \end{macro}
  2901. % \begin{macro}{\PercentIndex}
  2902. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2903. % \changes{v1.7c}{92/03/25}{Default now for bug-fixed makeindex}
  2904. % By default we assume a version of {\sf makeindex} without the
  2905. % percent bug is being used.
  2906. %    \begin{macrocode}
  2907. \@ifundefined{PercentIndex}
  2908.   {\def\PercentIndex{\it@is@a\percentchar}}{}
  2909. %    \end{macrocode}
  2910. % \end{macro}
  2911. % \begin{macro}{\OldMakeindex}
  2912. % \changes{v1.7c}{92/03/26}{Replaced `NewMakeIndex.}
  2913. % \begin{macro}{\percentchar}
  2914. %    Here is one solution for the percent bug in {\sf makeindex}.  The
  2915. %    macro \verb+\percentchar+ denotes a \verb+%+$_{12}$.
  2916. %    Calling this from a style option or the driver file sets things
  2917. %    up appropriately.\label{bug:fixes} 
  2918. %    \begin{macrocode}
  2919. \def\OldMakeindex{\def\PercentIndex{%
  2920.     \special@index{\quotechar\percentchar\actualchar\string\verb
  2921.            \quotechar*\verbatimchar\quotechar\bslash
  2922.            \percentchar\percentchar\verbatimchar}}}
  2923. {\catcode`\%=12 \gdef\percentchar{%}}
  2924. %    \end{macrocode}
  2925. % \end{macro}
  2926. % \end{macro}
  2927. % \subsection{Redefining the {\sf index} environment}
  2928. %\changes{v1.4r}{89/04/22}{twocols env. placed into separate file}
  2929. %\changes{v1.4?}{89/04/19}{use DEK's algorithm and implement
  2930. %                         a twocols env.}
  2931. %\changes{v1.4?}{89/04/16}{changes to the index env.}
  2932. %\changes{v1.5a}{89/04/26}{Now input multicol.sty instead of
  2933. %                         multcols.sty}
  2934. % \begin{macro}{\ifhave@multicol}
  2935. % \changes{v1.7a}{92/03/04}{Added to support avoiding multicol.sty}
  2936. %    By default
  2937. %    the index is set in three columns, and will start on the same
  2938. %    page as, and underneath, the last part of the text of the
  2939. %    documented style file, if possible.  The last page will be
  2940. %    reformatted with balanced columns.  This requires the {\sf
  2941. %    multicols} environment which is described elsewhere.
  2942. % ^^A  described elsewhere (see page~\xrefto{mittelbachmulti}).
  2943. %    So that {\sf doc} can be run independently of {\tt multicol.sty}
  2944. %    we first check for its existence and set the "have@multicol" flag
  2945. %    appropriately for use below.
  2946. %    \begin{macrocode}
  2947. \newif\ifhave@multicol
  2948. \openin\@ne multicol.sty
  2949. \ifeof\@ne \else \have@multicoltrue \fi
  2950. \closein\@ne \relax
  2951. %    \end{macrocode}
  2952. %    On systems where it is impossible to determine the existence of a
  2953. %    file using the above method the docstrip program can be directed
  2954. %    to force using multicol by including the next line.
  2955. % \changes{v1.7i}{92/07/14}{Force use of multicol.sty if necessary.}
  2956. %    \begin{macrocode}
  2957. %<+multicol>\have@multicoltrue
  2958. %    \end{macrocode}
  2959. % \end{macro}
  2960. %    If we found {\tt multicol.sty} we use it.  It would be nice to
  2961. %    delay this (and the re-definition of "theindex") until we knew
  2962. %    whether an index was actually required \ldots
  2963. %    \begin{macrocode}
  2964. \ifhave@multicol \input{multicol.sty} \fi
  2965. %    \end{macrocode}
  2966. % \begin{macro}{\IndexMin}
  2967. % \begin{macro}{\c@IndexColumns}
  2968. %    \changes{v1.4t}{89/04/24}{Counter added.}
  2969. %    If {\tt multicol} is in use,
  2970. %    when the index is started we compute the remaining space on the
  2971. %    current page; if it is greater than \verb+\IndexMin+, the first
  2972. %    part of the index will then be placed in the available space.
  2973. %    The number of columns set is controlled by the counter
  2974. %    \verb+\c@IndexColumns+ which can be changed with a
  2975. %    \verb+\setcounter+ declaration.
  2976. %    \begin{macrocode}
  2977. \newdimen\IndexMin         \IndexMin       = 80pt
  2978. \newcount\c@IndexColumns   \c@IndexColumns = 3
  2979. %    \end{macrocode}
  2980. % \end{macro}
  2981. % \end{macro}
  2982. % \begin{macro}{\theindex}
  2983. %    Now we start the multi-column mechanism, if appropriate. We use the
  2984. %    \verb+\c@IndexColumns+ \LaTeX{} counter declared above to denote
  2985. %    the number of columns and insert the `index prologue' text (which
  2986. %    might contain a \verb+\section+ call, etc.). See the default
  2987. %    definition for an example.
  2988. %    \changes{v1.4t}{89/04/24}{Incorporated new multicols env.}
  2989. %    \changes{v1.5a}{89/04/26}{Call multicols first}
  2990. %    \changes{v1.6e}{91/04/03}{Turned into env definition.}
  2991. %    \changes{v1.7a}{92/03/04}{Include test for multicols.}
  2992. %    \begin{macrocode}
  2993. \ifhave@multicol
  2994.   \renewenvironment{theindex}
  2995.     {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]%
  2996. %    \end{macrocode}
  2997. %    Then we make a few last minute assignments to read the individual
  2998. %    index \verb+\item+$\,$s and finish off by ignoring any initial
  2999. %    space.
  3000. %    \begin{macrocode}
  3001.       \IndexParms \let\item\@idxitem \ignorespaces}%
  3002. %    \end{macrocode}
  3003. % \end{macro}
  3004. % \begin{macro}{\endtheindex}
  3005. %    \changes{v1.4t}{89/04/24}{Incorporated new multicols env.}
  3006. %    At the end of the index, we have only to end the {\sf multicols}
  3007. %    environment.
  3008. %    \begin{macrocode}
  3009.     {\end{multicols}}
  3010. %    \end{macrocode}
  3011. %    If we can't use {\sf multicols} we warn the user and use an
  3012. %    environment that's basically the one from {\tt article.sty}.
  3013. %    \begin{macrocode}
  3014. \else
  3015.   \typeout{Can't find multicols.sty -- will use normal index layout if
  3016.      necessary.} 
  3017.   \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi
  3018.     \columnseprule \z@  \columnsep 35\p@
  3019.     \twocolumn[\index@prologue]%
  3020.     \IndexParms \let\item\@idxitem \ignorespaces}
  3021.   \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi}
  3022. %    \end{macrocode}
  3023. % \end{macro}
  3024. % Here are the necessary {\sf makeindex} declarations. We disable
  3025. % scanning of macro names inside the index with "\scan@allowedfalse\n"
  3026. % to avoid recursion.
  3027. %    \begin{macrocode}
  3028. %</style>
  3029. %<+gind>preamble
  3030. %<+gind>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
  3031. %<+gind>postamble
  3032. %<+gind>"\n\n \\end{theindex}\n"
  3033. %<*style>
  3034. %    \end{macrocode}
  3035. % \begin{macro}{\IndexPrologue}
  3036. % \begin{macro}{\index@prologue}
  3037. %    The \verb+\IndexPrologue+ macro is used to place a short message
  3038. %    into the document above the index.  It is implemented by
  3039. %    redefining \verb+\index@prologue+, a macro which holds the
  3040. %    default text.  We'd better make it a \verb+\long+ macro to allow
  3041. %    \verb+\par+ commands in its argument.
  3042. %    \begin{macrocode}
  3043. \long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack}
  3044. %    \end{macrocode}
  3045. %    Now we test whether the default is already defined by another
  3046. %    style file. If not we define it.
  3047. %    \begin{macrocode}
  3048. \@ifundefined{index@prologue}
  3049.      {\def\index@prologue{\section*{Index}%
  3050.                  \markboth{Index}{Index}%
  3051.                  The italic numbers denote the pages where the
  3052.                  corresponding entry is described,
  3053.                  numbers underlined point to the definition,
  3054.                  all others indicate the places where it is used.
  3055.                  }}{}
  3056. %    \end{macrocode}
  3057. % \end{macro}
  3058. % \end{macro}
  3059. % \begin{macro}{\IndexParms}
  3060. %    These are some last-minute assignments for formatting the index
  3061. %    entries. They are defined in a separate macro so that a user can
  3062. %    substitute different definitions.  We start by defining the
  3063. %    various parameters controlling leading and the separation between
  3064. %    the two columns.  The entire index is set in \verb+\small+ size.
  3065. %    \begin{macrocode}
  3066. \@ifundefined{IndexParms}
  3067.     {\def\IndexParms{%
  3068.        \parindent \z@
  3069.        \columnsep 15pt
  3070.        \parskip 0pt plus 1pt
  3071.        \rightskip 15pt
  3072.        \mathsurround \z@
  3073.        \parfillskip=-15pt
  3074.         \small
  3075. %    \end{macrocode}
  3076. % \begin{macro}{\@idxitem}
  3077. % \begin{macro}{\subitem}
  3078. % \begin{macro}{\subsubitem}
  3079. %    Index items are formatted with hanging indentation for any items
  3080. %    which may require more than one line.
  3081. %    \begin{macrocode}
  3082.        \def\@idxitem{\par\hangindent 30pt}%
  3083. %    \end{macrocode}
  3084. %    Any sub-item in the index is formatted with a 15pt indentation
  3085. %    under its main heading.
  3086. %    \begin{macrocode}
  3087.        \def\subitem{\@idxitem\hspace*{15pt}}%
  3088. %    \end{macrocode}
  3089. %    Whilst sub-sub-items go in a further 10pt.
  3090. %    \begin{macrocode}
  3091.        \def\subsubitem{\@idxitem\hspace*{25pt}}%
  3092. %    \end{macrocode}
  3093. % \begin{macro}{\indexspace}
  3094. %    The {\sf makeindex} program generates an \verb+\indexspace+
  3095. %    before each new alphabetic section commences. After this final
  3096. %    definition we end the \verb+\@ifundefined+ and the definition of
  3097. %    \verb+\IndexParms+.
  3098. %    \begin{macrocode}
  3099.        \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}%
  3100.       }}{}
  3101. %    \end{macrocode}
  3102. % \end{macro}
  3103. % \end{macro}
  3104. % \end{macro}
  3105. % \end{macro}
  3106. % \end{macro}
  3107. % \begin{macro}{\efill}
  3108. %    This definition of \verb+\efill+ is intended to be used after
  3109. %    index items which have no following text (for example, ``{\it
  3110. %    see\/}'' entries).  It just ensures that the current line is
  3111. %    filled, preventing ``\verb+Underfull \hbox+'' messages.
  3112. %    \begin{macrocode}
  3113. \def\efill{\hfill\nopagebreak}%
  3114. %</style>
  3115. %<+gind|gglo>item_x1   "\\efill \n \\subitem "
  3116. %<+gglo>item_x2   "\\ "
  3117. %<+gind>item_x2   "\\efill \n \\subsubitem "
  3118. %<*style>
  3119. %    \end{macrocode}
  3120. % \end{macro}
  3121. % \begin{macro}{\pfill}
  3122. % \begin{macro}{\dotfil}
  3123. % \begin{macro}{\dotfill}
  3124. %     The following definitions provide the \verb+\pfill+ command; if
  3125. %    this is specified in the index style file to {\sf makeindex} as
  3126. %    the delimiter to appear after index items, then the intervening
  3127. %    space before the referenced page numbers will be filled with
  3128. %    dots, with a little white space interpolated at each end of the
  3129. %    dots.  If the line is broken the dots will show up on both lines.
  3130. %    \begin{macrocode}
  3131. \def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus  1fill}%
  3132. \def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil}%
  3133. \def\pfill{\unskip~\dotfill\penalty500\strut\nobreak
  3134.                \dotfil~\ignorespaces}%
  3135. %</style>
  3136. %<+gind|gglo>delim_0   "\\pfill "
  3137. %<+gind|gglo>delim_1   "\\pfill "
  3138. %<+gind|gglo>delim_2   "\\pfill "
  3139. %<*style>
  3140. %    \end{macrocode}
  3141. % \end{macro}
  3142. % \end{macro}
  3143. % \end{macro}
  3144. % \begin{macro}{\*}
  3145. %    Here is the definition for the \verb+\*+ macro. It isn't used in
  3146. %    this set of macros.
  3147. %    \begin{macrocode}
  3148. \def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}}
  3149. %    \end{macrocode}
  3150. % \end{macro}
  3151. % \begin{macro}{\main}
  3152. %    The {\it defining\/} entry for a macro name is flagged with the
  3153. %    string {\tt\encapchar main}\footnote{With the current definition
  3154. %    of {\tt\bslash encapchar} substituted for {\tt\encapchar}} in the
  3155. %    \verb+\index+ command; {\sf makeindex} processes this so that the
  3156. %    \verb+\main+ macro will be invoked to underline the page
  3157. %    number(s) on which the {\em definition\/} of the macro will be
  3158. %    found.
  3159. %    \begin{macrocode}
  3160. \@ifundefined{main}{\def\main#1{\underline{#1}}}{}
  3161. %    \end{macrocode}
  3162. % \end{macro}
  3163. % \begin{macro}{\usage}
  3164. %    The \verb+\usage+ macro is used to indicate entries describing
  3165. %    the usage of a macro. The corresponding page number(s) will be
  3166. %    set in {\it italics}.
  3167. %    \begin{macrocode}
  3168. \@ifundefined{usage}{\def\usage#1{{\it #1}}}{}
  3169. %    \end{macrocode}
  3170. % \end{macro}
  3171. % \begin{macro}{\PrintIndex}
  3172. % \changes{v1.5k}{89/09/04}{`printindex changed to `PrintIndex.}
  3173. % \changes{v1.7a}{92/02/26}{Documentation moved to interface section.}
  3174. % \begin{macro}{\printindex}
  3175. %    This is the same as "\printindex" in the {\sf makeidx} style.
  3176. %    \begin{macrocode}
  3177. \def\PrintIndex{\@input{\jobname.ind}}
  3178. %    \end{macrocode}
  3179. %    Since this macro was called \verb+\printindex+ in older versions
  3180. %    of {\tt doc.sty} we also provide the following definition.
  3181. %    \begin{macrocode}
  3182. \def\printindex{\typeout{\string\printindex\space is obsolete!}%
  3183.                 \typeout{Please use \string\PrintIndex\space
  3184.                          if you are a macro implementor^^J
  3185.                          or get a newer version of the documented 
  3186.                          software if you are a user}%
  3187.                 \PrintIndex}
  3188. %    \end{macrocode}
  3189. % \end{macro}
  3190. % \end{macro}
  3191. % We want headings in the index (and changes list) according to the
  3192. % initial character of the next block of entries and have to instruct
  3193. % {\sf makeindex} appropriately.  Unfortunately the specification for
  3194. % this changed sometime between versions 2.4 and 2.11 of {\sf
  3195. % makeindex}.  We provide both ways of doing it but unfortunately this
  3196. % will always produce a warning message from {\sf makeindex}.  This is
  3197. % for older versions:
  3198. %  \changes{v1.7h}{92/07/01}{Turn off headings in gls file}
  3199. %    \begin{macrocode}
  3200. %</style>
  3201. %<+gind,gglo>% The next lines will produce some warnings when
  3202. %<+gind,gglo>% running Makeindex as they try to cover two different
  3203. %<+gind,gglo>% versions of the program:
  3204. %<+gind,gglo>lethead_prefix   "{\\bf\\hfil "
  3205. %<+gind,gglo>lethead_suffix   "\\hfil}\\nopagebreak\n"
  3206. %<+gind>lethead_flag       1
  3207. %<+gglo>lethead_flag       0
  3208. %    \end{macrocode}
  3209. % This works for newer ones:
  3210. %    \begin{macrocode}
  3211. %<+gind,gglo>heading_prefix   "{\\bf\\hfil "
  3212. %<+gind,gglo>heading_suffix   "\\hfil}\\nopagebreak\n"
  3213. %<+gind>headings_flag       1
  3214. %<+gglo>headings_flag       0
  3215. %<*style>
  3216. %    \end{macrocode}
  3217. % \subsection[Dealing with the change history]
  3218. %            {Dealing with the change history\footnotemark}
  3219. % \footnotetext{The whole section was proposed by Brian {\sc Hamilton
  3220. %               Kelly}. He also documented and debugged the macros as
  3221. %               well as many other parts of this style option.}
  3222. % To provide a change history log, the \verb+\changes+ command has
  3223. % been introduced.  This takes three arguments, respectively, the
  3224. % version number of the file, the date of the change, and some detail
  3225. % regarding what change has been made.  The first of these arguments
  3226. % is otherwise ignored, but the others are written out and may be used
  3227. % to generate a history of changes, to be printed at the end of the
  3228. % document.  However, note that older versions of Chen's standard {\sf
  3229. % makeindex} 
  3230. % program limit any textual field to just 64 characters; therefore,
  3231. % is important that the number of characters in the second and third
  3232. % parameters should not exceed 61 altogether (to allow for the
  3233. % parentheses placed around the date).
  3234. % \begin{macro}{\changes}
  3235. % \changes{BHK}{89/04/26}{Documented {\tt\protect\bslash changes}
  3236. %                         command.}
  3237. % \changes{BHK}{89/04/26}{Changed definition of
  3238. %                         {\tt\protect\bslash protect}.}
  3239. %    The output of
  3240. %    the \verb+\changes+ command goes into the \meta{Glossary\_File}
  3241. %    and therefore uses the normal \verb+\glossaryentry+
  3242. %    commands.\footnote{Note that a recent change in \LaTeX{} 2.09
  3243. %    changed the command name in the {\tt.glo} file from {\tt\bslash
  3244. %    indexentry} to {\tt\bslash glossaryentry}.  It is therefore
  3245. %    necessary to have a special {\sf makeindex} style file called {\tt
  3246. %    gglo.ist} to process this file correctly.} Thus {\sf makeindex}
  3247. %    or a similar program can be used to process the output into a
  3248. %    sorted ``glossary''.  The \verb+\changes+ command commences by
  3249. %    taking the usual measures to hide its spacing, and then redefines
  3250. %    \verb+\protect+ for use within the argument of the generated
  3251. %    \verb+\indexentry+ command. 
  3252. %    We re-code nearly all chars found in \verb+\sanitize+ to letter
  3253. %    since the use of special style options which make some characters
  3254. %    active might upset the \verb+\changes+ command when writing its
  3255. %    entries to the file. However we have to leave \verb+%+ as comment
  3256. %    and \verb*+ + as \meta{space} otherwise chaos will happen.
  3257. %    And, of course the \verb+\+ should be available as escape
  3258. %    character.
  3259. % \changes{v1.5v}{90/01/28}{`Re-code a lot of chars.}
  3260. % \changes{v1.5m}{89/09/20}{`actualchar in second level removed.}
  3261. % \changes{v1.5o}{89/09/24}{New sorting.}
  3262. % \changes{v1.6c}{90/06/29}{Again new sorting.}
  3263. %    \begin{macrocode}
  3264. \def\changes{\@bsphack\begingroup\@sanitize
  3265.    \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
  3266.    \changes@}
  3267. \def\changes@#1#2#3{%
  3268.   \def\protect##1{\string##1\space}%
  3269.   \edef\@tempa{\noexpand\glossary{#1\levelchar
  3270.                                  \expandafter\@gobble
  3271.                                  \saved@macroname\actualchar
  3272.                                  \string\verb\quotechar*%
  3273.                                  \verbatimchar\saved@macroname
  3274.                                  \verbatimchar:\levelchar #3}}%
  3275.   \@tempa\endgroup\@esphack}
  3276. %    \end{macrocode}
  3277. % \begin{macro}{\saved@macroname}
  3278. % \changes{BHK}{89/04/26}{Provided for sorting outside
  3279. %                         {\sf macro} environment}
  3280. %    The entries are sorted for convenience by the name of the most
  3281. %    recently introduced macroname (i.e., that in the most recent
  3282. %    \verb+\begin{macro}+ command).  We therefore provide
  3283. %    \verb+\saved@macroname+ to record that argument, and provide a
  3284. %    default definition in case \verb+\changes+ is used outside a {\sf
  3285. %    macro} environment.  (This is a {\em wicked\/} hack to get such
  3286. %    entries at the beginning of the sorted list!  It works providing no
  3287. %    macro names start with "!" or \verb+"+.)
  3288. %    \changes{v1.7a}{92/03/02}{Changed string used for better sorting.}
  3289. %    \begin{macrocode}
  3290. \def\saved@macroname{"General"}
  3291. %    \end{macrocode}
  3292. % \end{macro}
  3293. % \begin{macro}{\RecordChanges}
  3294. % \changes{BHK}{89/04/26}{Renames former {\tt\protect\bslash
  3295. %                         PrintChanges} command.}
  3296. %    To cause the changes to be written (to a {\tt.glo}) file, we
  3297. %    define \verb+\RecordChanges+ to invoke \LaTeX's usual
  3298. %    \verb+\makeglossary+ command.
  3299. %    \begin{macrocode}
  3300. \let\RecordChanges\makeglossary
  3301. %    \end{macrocode}
  3302. % \end{macro}
  3303. % \end{macro}
  3304. % \begin{macro}{\GlossaryMin}
  3305. %    \changes{BHK}{89/04/26}{Added to support
  3306. %                            {\tt\protect\bslash changes}.}
  3307. % \begin{macro}{\c@GlossaryColumns}
  3308. %    \changes{BHK}{89/04/26}{Added to support
  3309. %                            {\tt\protect\bslash changes}.}
  3310. %    The remaining macros are all analogues of those used for the {\sf
  3311. %    theindex} environment.  When the glossary is started we compute
  3312. %    the space which remains at the bottom of the current page; if
  3313. %    this is greater than \verb+\GlossaryMin+ then the first part of
  3314. %    the glossary will be placed in the available space.  The number
  3315. %    of columns set are controlled by the counter
  3316. %    \verb+\c@GlossaryColumns+ which can be changed with a
  3317. %    \verb+\setcounter+ declaration.
  3318. %    \begin{macrocode}
  3319. \newdimen\GlossaryMin         \GlossaryMin       = 80pt
  3320. \newcount\c@GlossaryColumns   \c@GlossaryColumns = 2
  3321. %    \end{macrocode}
  3322. % \end{macro}
  3323. % \end{macro}
  3324. % \begin{macro}{\theglossary}
  3325. %  \changes{BHK}{89/04/26}{Added to support
  3326. %                            {\tt\protect\bslash changes}.}
  3327. % \changes{v1.5p}{89/09/28}{Now call `multicols first.}
  3328. %    \changes{v1.6e}{91/04/03}{Turned into env definition.}
  3329. %    \changes{v1.7a}{92/03/10}{Changed to work without multicols if
  3330. %                              necessary.}
  3331. % \begin{macro}{\endglossary}
  3332. %    \changes{BHK}{89/04/26}{Added to support
  3333. %                            {\tt\protect\bslash changes}.}
  3334. %    The environment {\sf theglossary} is defined in the same manner
  3335. %    as the {\sf theindex} environment.
  3336. %    \begin{macrocode}
  3337. \ifhave@multicol
  3338.   \newenvironment{theglossary}{%
  3339.     \begin{multicols}\c@GlossaryColumns
  3340.                      [\glossary@prologue][\GlossaryMin]%
  3341.     \GlossaryParms \let\item\@idxitem \ignorespaces}%
  3342.    {\end{multicols}}
  3343. \else
  3344.   \newenvironment{theglossary}{%
  3345.       \@restonecoltrue\if@twocolumn\@restonecolfalse\fi
  3346.       \columnseprule \z@  \columnsep 35\p@
  3347.       \twocolumn[\glossary@prologue]%
  3348.       \GlossaryParms \let\item\@idxitem \ignorespaces}
  3349.     {\if@restonecol\onecolumn\else\clearpage\fi}
  3350. %    \end{macrocode}
  3351. % \end{macro}
  3352. % \end{macro}
  3353. % Here are the necessary {\sf makeindex} declarations with scanning
  3354. % disabled as for the index.
  3355. %    \begin{macrocode}
  3356. %</style>
  3357. %<+gglo>preamble
  3358. %<+gglo>"\n \\begin{theglossary} \n
  3359. %<+gglo>    \\makeatletter\\scan@allowedfalse\n"
  3360. %<+gglo>postamble
  3361. %<+gglo>"\n\n \\end{theglossary}\n"
  3362. %    \end{macrocode}
  3363. % This difference from {\tt gind.ist} is necessary if you have an
  3364. % up-to-date \LaTeX. 
  3365. %    \begin{macrocode}
  3366. %<+gglo>keyword "\\glossaryentry"
  3367. %<*style>
  3368. %    \end{macrocode}
  3369. % \begin{macro}{\GlossaryPrologue}
  3370. %    \changes{BHK}{89/04/26}{Added to support
  3371. %                            {\tt\protect\bslash changes}.}
  3372. % \begin{macro}{\glossary@prologue}
  3373. %    \changes{BHK}{89/04/26}{Added to support
  3374. %                            {\tt\protect\bslash changes}.}
  3375. %    The \verb+\GlossaryPrologue+ macro is used to place a short
  3376. %    message above the glossary into the document.  It is implemented
  3377. %    by redefining \verb+\glossary@prologue+, a macro which holds the
  3378. %    default text.  We better make it a long macro to allow
  3379. %    \verb+\par+ commands in its argument.
  3380. %    \begin{macrocode}
  3381. \long\def\GlossaryPrologue#1{\@bsphack
  3382.                              \def\glossary@prologue{#1}%
  3383.                              \@esphack}
  3384. %    \end{macrocode}
  3385. %    Now we test whether the default is already defined by another
  3386. %    style file. If not we define it.
  3387. %    \begin{macrocode}
  3388. \@ifundefined{glossary@prologue}
  3389.      {\def\glossary@prologue{\section*{{Change History}}%
  3390.                  \markboth{{Change History}}{{Change History}}%
  3391.                  }}{}
  3392. %    \end{macrocode}
  3393. % \end{macro}
  3394. % \end{macro}
  3395. % \begin{macro}{\GlossaryParms}
  3396. %    \changes{BHK}{89/04/26}{Added to support
  3397. %                            {\tt\protect\bslash changes}.}
  3398. % Unless the user specifies otherwise, we set the change history
  3399. % using the same parameters as for the index.
  3400. %    \begin{macrocode}
  3401. \@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms}{}
  3402. %    \end{macrocode}
  3403. % \end{macro}
  3404. % \begin{macro}{\PrintChanges}
  3405. %    \changes{BHK}{89/04/26}{Added to support
  3406. %                            {\tt\protect\bslash changes}.}
  3407. %    To read in and print the sorted change history, just put the
  3408. %    \verb+\PrintChanges+ command as the last (commented-out, and thus
  3409. %    executed during the documentation pass through the file) command
  3410. %    in your style file.  Alternatively, this command may form one of
  3411. %    the arguments of the \verb+\StopEventually+ command, although a
  3412. %    change history is probably {\em not\/} required if only the
  3413. %    description is being printed.
  3414. %    The command assumes that {\sf makeindex} or some other program
  3415. %    has processed the {\tt.glo} file to generate a sorted {\tt.gls}
  3416. %    file.
  3417. %    \begin{macrocode}
  3418. \def\PrintChanges{\@input{\jobname.gls}}
  3419. %    \end{macrocode}
  3420. % \end{macro}
  3421. %    
  3422. % \subsection{Bells and whistles}
  3423. % \begin{macro}{\StopEventually}
  3424. % \changes{v1.5k}{89/09/04}{Support for checksum.}
  3425. % \begin{macro}{\Finale}
  3426. % \changes{v1.5k}{89/09/04}{Support for checksum.}
  3427. % \changes{v1.5z}{90/04/22}{Define `Finale globally.}
  3428. % \begin{macro}{\OnlyDescription}
  3429. %    Here is the default definition for \verb+\StopEventually+, we
  3430. %    simply save its argument in the macro \verb+\Finale+.
  3431. %    \begin{macrocode}
  3432. \long\def\StopEventually#1{\@bsphack\gdef\Finale{#1%
  3433. %    \end{macrocode}
  3434. %    But \verb+\Finale+ will be called at the very end of a file. This
  3435. %    is exactly the point were we want to know if the file is
  3436. %    uncorrupted. Therefore we call \verb+\check@checksum+ at this
  3437. %    point. 
  3438. %    \begin{macrocode}
  3439.               \check@checksum}%
  3440. %    \end{macrocode}
  3441. %    On the other hand: \verb+\StopEventually+ is more or less a
  3442. %    dividing point between description and code. So we start to look
  3443. %    for the check-sum of the documented file by calling
  3444. %    \verb+\init@checksum+. 
  3445. %    \begin{macrocode}
  3446.            \init@checksum
  3447.            \@esphack}
  3448. %    \end{macrocode}
  3449. %    When the user places an \verb+\OnlyDescription+ declaration in
  3450. %    the driver file the document should only be typeset up to
  3451. %    \verb+\StopEventually+. We therefore have to redefine this macro.
  3452. %    \begin{macrocode}
  3453. \def\OnlyDescription{\@bsphack\long\def\StopEventually##1{%
  3454. %    \end{macrocode}
  3455. %    In this case the argument of \verb+\StopEventually+ should be set
  3456. %    and afterwards \TeX{} should stop reading from this file.
  3457. %    Therefore we finish this macro with
  3458. %    \begin{macrocode}
  3459.            ##1\endinput}\@esphack}
  3460. %    \end{macrocode}
  3461. % \end{macro}
  3462. % \end{macro}
  3463. % \end{macro}
  3464. % \begin{macro}{\meta}
  3465. % \changes{v1.4t}{89/04/24}{Macro added.}
  3466. % \begin{macro}{\m@ta}
  3467. % \changes{v1.5w}{90/02/03}{Breaks at space allowed.}
  3468. % \changes{v1.6a}{90/05/24}{Extra space bug corrected.}
  3469. %    The \verb+\meta+ macro is a bit tricky. We want to allow line
  3470. %    breaks at blanks in the argument but we don't want a break
  3471. %    in between. We therefore define \verb+\meta+ in a way that a
  3472. %    \verb*+ + is active when the argument is scanned. Words are then
  3473. %    scanned into \verb+\hbox+es. The active \verb*+ + will end the
  3474. %    preceding \verb+\hbox+ add an ordinary space and open a new
  3475. %    \verb+\hbox+. In this way breaks are only possible at spaces.  It
  3476. %    would be even better to forbid page breaks but this is not
  3477. %    possible in an all cases.
  3478. %    \begin{macrocode}
  3479. \begingroup
  3480. \obeyspaces%
  3481. \catcode`\^^M\active%
  3482. %    \end{macrocode}
  3483. %    We have to be careful to end all lines with a \verb+%+ sign in
  3484. %    this definition.
  3485. %    \begin{macrocode}
  3486. \gdef\meta{\begingroup\obeyspaces\catcode`\^^M\active%
  3487. \let^^M\do@space\let \do@space%
  3488. %    \end{macrocode}
  3489. %    To allow to break up words inside the \verb+\meta+ command we
  3490. %    redefine the \verb+\-+ command. It now has to end the last
  3491. %    open box, add a discretionary and start the next one for the
  3492. %    rest of the current word. See below for more details.
  3493. %    Finally we call \verb+\m@ta+ which
  3494. %    will scan the argument of \verb+\meta+.
  3495. %    \begin{macrocode}
  3496. \def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\it}%
  3497. \m@ta}%
  3498. \endgroup
  3499. %    \end{macrocode}
  3500. %    We start \verb+\m@ta+ by opening an \verb+\hbox+.
  3501. %    Inside this box there will be angle brackets and the argument
  3502. %    typeset in italic typeface. If there are no spaces or \verb+\-+ 
  3503. %    commands in this argument the result will be a single box. But
  3504. %    when a space is encountered (which has \verb+\catcode+ 13) then
  3505. %    it will expand into \verb+\do@space+ which will close the current
  3506. %    box, output a space (so that we have a legitimate break point, and
  3507. %    then opens an new box to catch the rest of the argument.
  3508. % \changes{v1.6d}{90/11/16}{`leavevmode added.}
  3509. %    \begin{macrocode}
  3510. \def\m@ta#1{\leavevmode\hbox\bgroup$\langle$\it#1\/$\rangle$\egroup
  3511. %    \end{macrocode}
  3512. %    Finally, we have to close the group which was started in
  3513. %    \verb+\meta+ 
  3514. %    to restore all our changes.
  3515. %    \begin{macrocode}
  3516.     \endgroup}
  3517. %    \end{macrocode}
  3518. %    The \verb+\do@space+ macro will produce the possible breakpoint
  3519. %    by ending the current box (\verb+\egroup+) and adding the
  3520. %    \verb+\space+ 
  3521. %    into the surrounding paragraph.
  3522. %    \begin{macrocode}
  3523. \def\do@space{\egroup\space
  3524. %    \end{macrocode}
  3525. %    Then we start a new box, switching again to italic to catch the
  3526. %    rest of the argument of \verb+\meta+. But we also have to make sure
  3527. %    that any space following  directly will be ignored. Therefore we
  3528. %    check the following token and discard it as long as it is a token
  3529. %    with the meaning \verb+\do@space+, i.e.\ a $\verb*+ +_{13}$ or a
  3530. %    $\verb+^^M+_{13}$.
  3531. %    \begin{macrocode}
  3532.     \hbox\bgroup\it\futurelet\next\sp@ce}
  3533. \def\sp@ce{\ifx\next\do@space\expandafter\sp@@ce\fi}
  3534. \def\sp@@ce#1{\futurelet\next\sp@ce}
  3535. %    \end{macrocode}
  3536. % \end{macro}
  3537. % \end{macro}
  3538. % \begin{macro}{\IndexInput}
  3539. %    This next macro may be used to read in a separate file (possibly
  3540. %    a style file that is {\em not\/} documented by this means) and
  3541. %    set it verbatim, whilst scanning for macro names and indexing the
  3542. %    latter.  This could be a useful first pass in preparing to
  3543. %    generate documentation for the file read.
  3544. %    \begin{macrocode}
  3545. \def\IndexInput#1{%
  3546. %    \end{macrocode}
  3547. %     We commence by setting up a group, and initializing a
  3548. %    \verb+\trivlist+ as is normally done by a
  3549. %    \verb+\begin{macrocode}+ command.
  3550. %    \begin{macrocode}
  3551.      \begingroup \macro@code
  3552. %    \end{macrocode}
  3553. %    We also make spacing behave as in the {\sf macrocode}
  3554. %    environment, because otherwise all the spaces will be shown
  3555. %    explicitly.
  3556. %    \begin{macrocode}
  3557.    \frenchspacing \@vobeyspaces
  3558. %    \end{macrocode}
  3559. %    Then it only remains to read in the specified file, and finish
  3560. %    off the \verb+\trivlist+.
  3561. % \changes{v1.5t}{89/11/07}{Call `endmacrocode instead of `endtrivlist.}
  3562. %    \begin{macrocode}
  3563.      \input{#1}\endmacrocode
  3564. %    \end{macrocode}
  3565. %    Of course, we need to finish off the group as well.
  3566. %    \begin{macrocode}
  3567.      \endgroup}
  3568. %    \end{macrocode}
  3569. % \end{macro}
  3570. % \begin{macro}{\maketitle}
  3571. %    The macro to generate titles is easily altered in order that it
  3572. %    can be used more than once (an article with many titles).  In the
  3573. %    original, diverse macros were concealed after use with
  3574. %    \verb+\relax+. We must cancel anything that may have been put
  3575. %    into \verb+\@thanks+, etc., otherwise {\em all\/} titles will
  3576. %    carry forward any earlier such setting!
  3577. %  \changes{v1.5j}{89/06/09}{thispagestyle plain removed}
  3578. %    \begin{macrocode}
  3579. \def\maketitle{\par
  3580.       \begingroup \def \thefootnote {\fnsymbol {footnote}}%
  3581.       \setcounter {footnote}\z@
  3582.       \def \@makefnmark {\hbox to \z@{$^{\@thefnmark }$\hss }}%
  3583.       \if@twocolumn \twocolumn [\@maketitle ]%
  3584.       \else \newpage \global \@topnum \z@ \@maketitle \fi
  3585. %    \end{macrocode}
  3586. % \changes{v1.5k}{89/09/04}{Added {\tt\protect\bslash ps@titlepage}}
  3587. %    For special formatting requirements (such as in TUGboat), we use
  3588. %    pagestyle \verb+titlepage+ for this; this is later defined to be
  3589. %    \verb+plain+, unless already defined, as, for example, by
  3590. %    \verb+ltugboat.sty+.
  3591. %    \begin{macrocode}
  3592.        \thispagestyle{titlepage}\@thanks \endgroup
  3593. %    \end{macrocode}
  3594. %    If the driver file documents many files, we don't want parts of a
  3595. %    title of one to propagate to the next, so we have to cancel
  3596. %    these:
  3597. %    \begin{macrocode}
  3598.       \setcounter {footnote}\z@
  3599.       \gdef\@date{\today}\gdef\@thanks{}%
  3600.       \gdef\@author{}\gdef\@title{}}
  3601. %    \end{macrocode}
  3602. % \end{macro}
  3603. % \begin{macro}{\ps@titlepage}
  3604. % \changes{v1.5k}{89/09/04}{Added {\tt\protect\bslash ps@titlepage}}
  3605. %    When a number of articles are concatenated into a journal, for
  3606. %    example, it is not usual for the title pages of such documents to
  3607. %    be formatted differently.  Therefore, a style option such as {\sf
  3608. %    ltugboat} can define this macro in advance.  However, if no such
  3609. %    definition exists, we use pagestyle {\tt plain} for title pages.
  3610. %    \begin{macrocode}
  3611. \@ifundefined{ps@titlepage}
  3612.     {\let\ps@titlepage=\ps@plain}{}
  3613. %    \end{macrocode}
  3614. % \end{macro}
  3615. % \begin{macro}{\MakeShortVerb}
  3616. % \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters
  3617. %                           `dospecials, `@sanitize).} 
  3618. % This arranges an abbreviation for "\verb" such that if you say
  3619. % "\MakeShortVerb{\"\meta{c}"}" subsequently using
  3620. % \meta{c}\meta{text}\meta{c} is equivalent to
  3621. % "\verb"\meta{c}\meta{text}\meta{c}.\footnote{Warning:
  3622. % the commentary in the rest of this section was written by Dave
  3623. % Love.}  In addition, the fact 
  3624. % that \meta{c} is made active is recorded for the benefit of the
  3625. % {\sf verbatim} and {\sf macrocode} environments.
  3626. % Note particularly that the definitions below are global.
  3627. % The first thing we do (it needn't be first) is to record
  3628. % the---presumably new---special character in "\dospecials" and
  3629. % "\@sanitize" using "\add@special".
  3630. %    \begin{macrocode}
  3631. \def\MakeShortVerb#1{%
  3632.   \typeout{*** Made \expandafter\@gobble\string#1\space a short
  3633.            reference for \string\verb \on@line\space ***}%
  3634.   \add@special{#1}%
  3635. %    \end{macrocode}
  3636. % Then the character's current catcode is stored in "\cc\"\meta{c}.
  3637. %    \begin{macrocode}
  3638.   \expandafter
  3639.   \xdef\csname cc\string#1\endcsname{\the\catcode`#1}%
  3640. %    \end{macrocode}
  3641. % The character is spliced into the definition using the same trick as
  3642. % used in "\verb" (for instance), having activated "~" in a group.
  3643. %    \begin{macrocode}
  3644.   \begingroup
  3645.     \catcode`\~\active  \lccode`\~`#1%
  3646.     \lowercase{%
  3647. %    \end{macrocode}
  3648. % The character's old meaning is recorded in "\ac\"\meta{c} prior to
  3649. % assigning it a new one.
  3650. %    \begin{macrocode}
  3651.     \global\expandafter\let
  3652.        \csname ac\string#1\endcsname~%
  3653.     \gdef~{\verb~}}%
  3654.   \endgroup
  3655. %    \end{macrocode}
  3656. % Finally the character is made active.
  3657. %    \begin{macrocode}
  3658.   \global\catcode`#1\active}
  3659. %    \end{macrocode}
  3660. % \end{macro}
  3661. % \begin{macro}{\DeleteShortVerb}
  3662. % \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters
  3663. %                           `dospecials, `@sanitize).}
  3664. % Here's the means of undoing a "\MakeShortVerb", for instance in a
  3665. % region where you need to use the character outside a verbatim
  3666. % environment.  It arranges for "\dospecials" and "\@sanitize" to be
  3667. % altered appropriately, restores the saved catcode and, if necessary,
  3668. % the character's meaning (as stored by 
  3669. % "\MakeShortVerb").  If the catcode wasn't stored in
  3670. % "\cc\"\meta{c} (by "\MakeShortVerb") the command is silently
  3671. % ignored. 
  3672. % \changes{v1.7a}{92/02/28}{Check for previous matched `MakeShortVerb
  3673. %                           to avoid error.}
  3674. %    \begin{macrocode}
  3675. \def\DeleteShortVerb#1{%
  3676.   \expandafter\ifx\csname cc\string#1\endcsname\relax
  3677.   \else
  3678.     \typeout{*** Deleted \expandafter\@gobble\string#1\space as short
  3679.              reference for \string\verb \on@line\space ***}%
  3680.     \rem@special{#1}%
  3681.     \global\catcode`#1\csname cc\string#1\endcsname
  3682.     \ifnum\catcode`#1=\active
  3683.       \begingroup
  3684.         \catcode`\~\active   \lccode`\~`#1%
  3685.         \lowercase{%
  3686.           \global\expandafter\let\expandafter~%
  3687.           \csname ac\string#1\endcsname}%
  3688.       \endgroup \fi \fi}
  3689. %    \end{macrocode}
  3690. % \end{macro}
  3691. % \begin{macro}{\add@special}
  3692. % \changes{v1.7a}{92/02/27}{Added for short verb facility.}
  3693. % This helper macro adds its argument to the
  3694. % "\dospecials" macro which is conventionally used by verbatim macros
  3695. % to alter the catcodes of the currently active characters.  We need
  3696. % to add "\do\"\meta{c} to the expansion of "\dospecials" after
  3697. % removing the character if it was already there to avoid multiple
  3698. % copies building up should "\MakeShortVerb" not be balanced by
  3699. % "\DeleteShortVerb" (in case anything that uses "\dospecials" cares
  3700. % about repetitions).
  3701. %    \begin{macrocode}
  3702. \def\add@special#1{%
  3703.   \rem@special{#1}%
  3704.   \expandafter\gdef\expandafter\dospecials\expandafter
  3705.     {\dospecials \do #1}%
  3706. %    \end{macrocode}
  3707. % Similarly we have to add "\@makeother\"\meta{c} to "\@sanitize"
  3708. % (which is used in things like "\index" to re-catcode all special
  3709. % characters except braces).
  3710. %    \begin{macrocode}
  3711.   \expandafter\gdef\expandafter\@sanitize\expandafter
  3712.     {\@sanitize \@makeother #1}}
  3713. %    \end{macrocode}
  3714. % \end{macro}
  3715. % \begin{macro}{\rem@special}
  3716. % \changes{v1.7a}{92/02/27}{Added for short verb facility.}
  3717. % The inverse of "\add@special" is slightly trickier.  "\do" is
  3718. % re-defined to expand to nothing if its argument is the character of
  3719. % interest, otherwise to expand simply to the argument.  We can then
  3720. % re-define "\dospecials" to be the expansion of itself.  The space
  3721. % after "=`##1" prevents an expansion to "\relax"!
  3722. %    \begin{macrocode}
  3723. \def\rem@special#1{%
  3724.   \def\do##1{%
  3725.     \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}%
  3726.   \xdef\dospecials{\dospecials}%
  3727. %    \end{macrocode}
  3728. % Fixing "\@sanitize" is the same except that we need to re-define
  3729. % "\@makeother" which obviously needs to be done in a group. 
  3730. %    \begin{macrocode}
  3731.   \begingroup
  3732.     \def\@makeother##1{%
  3733.       \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}%
  3734.     \xdef\@sanitize{\@sanitize}%
  3735.   \endgroup}
  3736. %    \end{macrocode}
  3737. % \end{macro}
  3738. % \begin{macro}{\MakeShortverb}
  3739. % \begin{macro}{\DeleteShortverb}
  3740. % \changes{v1.7a}{92/02/27}{Added (from newdoc).}
  3741. % These commands from {\sf newdoc} are now obsolete.
  3742. %    \begin{macrocode}
  3743. \def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb
  3744.                          syntax, this is obsolete ***}\MakeShortVerb}
  3745. \def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb
  3746.                          syntax, this is obsolete ***}\DeleteShortVerb}
  3747. %    \end{macrocode}
  3748. % \end{macro}
  3749. % \end{macro}
  3750. % \subsection[Providing a checksum and character table]
  3751. %        {Providing a checksum and character table\footnotemark}
  3752. %        \footnotetext{Warning: the commentary in this section was
  3753. %                      written by Dave Love. }
  3754. % \begin{macro}{\init@checksum}
  3755. % The checksum mechanism works by counting backslashes in the
  3756. % macrocode.  This initialises the count (when called from
  3757. % "\StopEventually"). 
  3758. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  3759. %    \begin{macrocode}
  3760. \def\init@checksum{\relax
  3761.     \global\bslash@cnt\z@}
  3762. %    \end{macrocode}
  3763. % \end{macro}
  3764. % \begin{macro}{\check@checksum}
  3765. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  3766. % This reports the sum compared with the value ("\bslash@cnt") the
  3767. % file advertises.  It's called from "\Finale" (if that hasn't been
  3768. % re-defined). 
  3769. %    \begin{macrocode}
  3770. \def\check@checksum{\relax
  3771.      \ifnum\check@sum=\z@
  3772.        \typeout{**********************************}%
  3773.        \typeout{* This macro file has no checksum!}%
  3774.        \typeout{* The checksum should be \the\bslash@cnt!}%
  3775.        \typeout{**********************************}%
  3776.      \else
  3777.        \ifnum\check@sum=\bslash@cnt
  3778.          \typeout{*******************}%
  3779.          \typeout{* Checksum passed *}%
  3780.          \typeout{*******************}%
  3781.        \else
  3782.          \errhelp\wrong@checksum
  3783.          \errmessage{Checksum not passed 
  3784.                     (\the\check@sum<>\the\bslash@cnt)}%
  3785.         \fi
  3786.      \fi
  3787.      \global\check@sum\z@}
  3788. %    \end{macrocode}
  3789. % \end{macro}
  3790. % \begin{macro}{\check@sum}
  3791. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  3792. % \begin{macro}{\bslash@cnt}
  3793. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  3794. % \begin{macro}{\wrong@checksum}
  3795. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  3796. % We need to define the counter for the number of backslashes counted
  3797. % ("\bslash@cnt") and the value advertised by the file ("\check@sum")
  3798. % as well as a help message for when things go wrong.
  3799. %    \begin{macrocode}
  3800. \newcount\check@sum           \check@sum  = \z@
  3801. \newcount\bslash@cnt          \bslash@cnt = \z@
  3802. \newhelp\wrong@checksum
  3803.    {The currently documented file seems to be wrong.^^J%
  3804.     Try to get a correct version.}%
  3805. %    \end{macrocode}
  3806. % \end{macro}
  3807. % \end{macro}
  3808. % \end{macro}
  3809. % \begin{macro}{\CheckSum}
  3810. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  3811. % This is the interface to setting "\check@sum".
  3812. %    \begin{macrocode}
  3813. \def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack}
  3814. %    \end{macrocode}
  3815. % \end{macro}
  3816. % \begin{macro}{\step@checksum}
  3817. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  3818. % This advances the count when a backslash is encountered in the
  3819. % macrocode. 
  3820. %    \begin{macrocode}
  3821. \def\step@checksum{\global\advance\bslash@cnt\@ne}
  3822. %    \end{macrocode}
  3823. % \end{macro}
  3824. % \begin{macro}{\CharacterTable}
  3825. %    The user interface to the character table-checking does some
  3826. %    "\catcode"ing and then compares the following table with the
  3827. %    stored version. We need to have "@" of type ``other'' within the
  3828. %    table since this is the way it is usually returned when reading
  3829. %    in a normal document. To nevertheless have a private letter we
  3830. %    use "~" for this purpose. "~" does no harm as a ``letter'' as it
  3831. %    comes last in the table and therefore will not gobble following
  3832. %    space.
  3833. % \changes{v1.5m}{89/09/20}{Macro added to check character translation
  3834. %                           problems.}
  3835. % \changes{v1.5q}{89/11/01}{Made character table more readable.}
  3836. % \changes{v1.5t}{89/11/07}{Make \string\~{} letter in chartable
  3837. %                           macros.} 
  3838. % \changes{v1.5u}{89/11/14}{Made @ other in default table.}
  3839. %    \begin{macrocode}
  3840. \def\CharacterTable{\begingroup \CharTableChanges \character@table}
  3841. %    \end{macrocode}
  3842. % \end{macro}
  3843. % \def\MakePrivateLetters{\catcode`\~=11\makeatletter}
  3844. % \begin{macro}{\character@table}
  3845. % This does the work of comparing the tables and reporting the result.
  3846. % Note that the following code is enclosed in a group
  3847. % with "~" catcoded to letter.
  3848. %    \begin{macrocode}
  3849. \begingroup
  3850.   \catcode`\~=11
  3851.   \gdef\character@table#1{\def\used~table{#1}%
  3852.       \ifx\used~table\default~table
  3853.            \typeout{***************************}%
  3854.            \typeout{* Character table correct *}%
  3855.            \typeout{***************************}%
  3856.       \else
  3857.          \errhelp\wrong@table
  3858.          \errmessage{Character table corrupted}%
  3859.          \show\default~table
  3860.          \show\used~table
  3861.       \fi
  3862.       \endgroup}
  3863. %    \end{macrocode}
  3864. % \end{macro}
  3865. % \begin{macro}{\CharTableChanges}
  3866. %    When the character table is read in we need to scan it with a
  3867. %    fixed set of "\catcode"s. The reference table below  was defined by
  3868. %    assuming the normal "\catcode"s of \TeX{}, i.e.\ "@" is of type
  3869. %    other and the only token of type ``letter'' are the usual letters
  3870. %    of the alphabet. If, for some reason, other characters are made
  3871. %    ``letters'' then their "\catcode"s need to be restored before
  3872. %    checking the table. Otherwise spaces in the table are gobbled and
  3873. %    we get the information that the tables are different, even if
  3874. %    they are actually equal. For this reason "\CharTableChanges" can
  3875. %    be set up to locally restore the "\catcode"s of such ``letters''
  3876. %    to ``other''.
  3877. %    \begin{macrocode}
  3878.   \global\let\CharTableChanges\@empty
  3879. %    \end{macrocode}
  3880. % \end{macro}
  3881. % \begin{macro}{\default~table}
  3882. % Here's what the table {\em should\/} look like (modulo spaces).
  3883. %    \begin{macrocode}
  3884.   \makeatother
  3885.   \gdef\default~table
  3886.      {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
  3887.       Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
  3888.       Digits        \0\1\2\3\4\5\6\7\8\9
  3889.       Exclamation   \!     Double quote  \"     Hash (number) \#
  3890.       Dollar        \$     Percent       \%     Ampersand     \&
  3891.       Acute accent  \'     Left paren    \(     Right paren   \)
  3892.       Asterisk      \*     Plus          \+     Comma         \,
  3893.       Minus         \-     Point         \.     Solidus       \/
  3894.       Colon         \:     Semicolon     \;     Less than     \<
  3895.       Equals        \=     Greater than  \>     Question mark \?
  3896.       Commercial at \@     Left bracket  \[     Backslash     \\
  3897.       Right bracket \]     Circumflex    \^     Underscore    \_
  3898.       Grave accent  \`     Left brace    \{     Vertical bar  \|
  3899.       Right brace   \}     Tilde         \~}
  3900. \endgroup
  3901. %    \end{macrocode}
  3902. % \end{macro}
  3903. % \let\MakePrivateLetters=\makeatletter
  3904. % \begin{macro}{\wrong@table}
  3905. % \changes{v1.7a}{92/02/28}{Moved to where the catcodes are right so it
  3906. %                           works.} 
  3907. % We need a help message in case of problems.
  3908. %    \begin{macrocode}
  3909.   \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J
  3910.             I now \string\show\space you both tables for comparison.}
  3911. %    \end{macrocode}
  3912. % \end{macro}
  3913. % \subsection[Attaching line numbers to code lines]
  3914. %            {Attaching line numbers to code lines\footnotemark}
  3915. %            \footnotetext{Warning: the commentary was written by Dave
  3916. %            Love.}
  3917. % The code in this section allows index entries to refer to code line
  3918. % numbers---the number of the first line of macrocode in the {\sf macro}
  3919. % environment. 
  3920. % \begin{macro}{\codeline@index}
  3921. % Indexing by code line is controlled by the "codeline@index" switch.
  3922. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  3923. % \changes{v1.7a}{92/02/24}{Documented code line no. support.}
  3924. %    \begin{macrocode}
  3925. \newif\ifcodeline@index \codeline@indexfalse
  3926. %    \end{macrocode}
  3927. % \end{macro}
  3928. % \begin{macro}{\codeline@wrindex}
  3929. %    The code index entries are written out by "\special@index".  If
  3930. %    indexing is by code line this is "\let" to "\codeline@wrindex";
  3931. %    if indexing is by page it is just "\index".  However, if
  3932. %    "\nofiles" is given, we omit writing such an index entry at all.
  3933. % \changes{v1.7j}{92/08/14}{Added `if@filesw.}
  3934. %    \begin{macrocode}
  3935. \def\codeline@wrindex#1{\if@filesw
  3936.         \immediate\write\@indexfile
  3937.             {\string\indexentry{#1}%
  3938.             {\number\c@CodelineNo}}\fi}
  3939. %    \end{macrocode}
  3940. % \end{macro}
  3941. % \begin{macro}{\special@index}
  3942. % By default no index entries are written out.
  3943. %    \begin{macrocode}
  3944. \let\special@index = \@gobble
  3945. %    \end{macrocode}
  3946. % \end{macro}
  3947. % \begin{macro}{\CodelineIndex}
  3948. % \changes{v1.5u}{89/11/14}{Added `PageIndex and `CodelineIndex (Undoc)}
  3949. % This switches on use of the index file with "\makeindex", sets the
  3950. % switch to indicate code line numbering and defines "\special@index"
  3951. % appropriately. 
  3952. %    \begin{macrocode}
  3953. \def\CodelineIndex{\makeindex 
  3954.                    \codeline@indextrue
  3955.                    \let\special@index\codeline@wrindex}
  3956. %    \end{macrocode}
  3957. % \end{macro}
  3958. % \begin{macro}{\PageIndex}
  3959. % "\PageIndex" is similar.
  3960. %    \begin{macrocode}
  3961. \def\PageIndex{\makeindex 
  3962.                \codeline@indexfalse
  3963.                \let\special@index\index}
  3964. %    \end{macrocode}
  3965. % \end{macro}
  3966. % \begin{macro}{\c@CodelineNo}
  3967. % \changes{v1.5l}{89/09/10}{Counter added to support code line numbers.}
  3968. % \changes{v1.5y}{90/02/24}{Default changed.}
  3969. % \changes{v1.6b}{90/06/15}{`rm moved before `scriptsize to
  3970. %                           avoid unnecessary fontwarning.}
  3971. % We need a counter to keep track of the line number.
  3972. %    \begin{macrocode}
  3973. \newcount\c@CodelineNo  \c@CodelineNo\z@
  3974. %    \end{macrocode}
  3975. % \end{macro}
  3976. % \begin{macro}{\theCodelineNo}
  3977. % \changes{v1.7a}{92/02/25}{Existing definition not overwritten.}
  3978. % \changes{v1.7a}{92/03/12}{Use `reset@font for NFSS.}
  3979. % This provides a hook to control the format of line numbers which may
  3980. % be defined in a style file.
  3981. %    \begin{macrocode}
  3982. \@ifundefined{theCodelineNo}
  3983.   {\ifx\selectfont\undefined
  3984.      \def\theCodelineNo{\rm\scriptsize\arabic{CodelineNo}}%
  3985.    \else
  3986.      \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}%
  3987.    \fi}
  3988.   {} 
  3989. %    \end{macrocode}
  3990. % \end{macro}
  3991. % \subsection{Layout Parameters for documenting style files}
  3992. % \begin{macro}{\tolerance}
  3993. %    People documenting style files would probably rather have things
  3994. %    ``sticking out'' in overfull \verb+\hbox+es and poorish spacing,
  3995. %    because they probably don't want to spend a lot of time on making
  3996. %    all the line breaks perfect!
  3997. %    \begin{macrocode}
  3998.        \tolerance=1000\relax
  3999. %    \end{macrocode}
  4000. % \end{macro}
  4001. % \DeleteShortVerb{\"}
  4002. % The following \verb+\mathcode+ definitions allow the characters
  4003. % `\verb+\+'
  4004. % and `{\tt @}' to appear in \verb+\tt+ font when invoked in math 
  4005. % mode;\footnote{You may wonder why the definitions state that both
  4006. %                characters belong to the {\em variable family\/}
  4007. %                (i.e.\ the number 7 in front). The reason is this:
  4008. %                Originally the {\tt\bslash mathcode} of
  4009. %                {\tt\bslash} was defined to be {\tt "075C},
  4010. %                i.e.\ ordinary character number 92 (hex 5C) in
  4011. %                math family number 7 which is the typewriter family in
  4012. %                standard \LaTeX.
  4013. %                But this file should not depend on this specific
  4014. %                setting, so I changed these {\tt\bslash mathcode}$\,$s
  4015. %                to work with any family assignments. For an example
  4016. %                see the article about the new font selection scheme.}
  4017. % particularly for something like $\verb+\@abc+=1$.
  4018. % If an {\em old\/} version of the {\sf german} style option is in
  4019. % force, then the `\verb+"+' character is active and would upset the
  4020. % definition of the \meta{16-bit number} quantities below, therefore
  4021. % we change the \verb+\catcode+ of \verb+"+ inside a group, and use
  4022. % \verb+\global+.
  4023. %    \begin{macrocode}
  4024. { \catcode`\"=12
  4025.   \global\mathcode`\\="705C \global\mathcode`\@="7040 }
  4026. %    \end{macrocode}
  4027. % \MakeShortVerb{\"}
  4028. % \begin{macro}{\DocstyleParms}
  4029. %    This macro can be used, for example, to assign new values to
  4030. %    \verb+\MacrocodeTopsep+ and \verb+\MacroIndent+ and some other
  4031. %    internal registers.  If it is already defined, the default
  4032. %    definition won't be carried out. Note that it is necessary to
  4033. %    assign new values via this macro if it should be done in a style
  4034. %    file (like {\tt ltugboat.sty} for example) since the registers are
  4035. %    undefined before {\tt doc.sty} is read in.  The default values
  4036. %    for the internal registers are scattered over this file.
  4037. % \changes{v1.5u}{89/11/14}{`DocStyleParms now empty}
  4038. %    \begin{macrocode}
  4039. \@ifundefined{DocstyleParms}{}{}
  4040. %    \end{macrocode}
  4041. %    Now we allow overwriting the values by calling
  4042. %    \verb+\DocstyleParms+.
  4043. %    \begin{macrocode}
  4044. \DocstyleParms     \let\DocstyleParms\relax
  4045. %    \end{macrocode}
  4046. % \end{macro}
  4047. % \begin{macro}{\AmSTeX}
  4048. %   \changes{v1.5j}{89/06/09}{Macro AmsTeX renamed to AmSTeX}
  4049. % \begin{macro}{\BibTeX}
  4050. % \begin{macro}{\SliTeX}
  4051. %    Here are a few definitions which can usefully be employed when
  4052. %    documenting style files: now we can readily refer to \AmSTeX,
  4053. %    \BibTeX\ and \SliTeX, as well as the usual \TeX\ and \LaTeX.
  4054. %    \begin{macrocode}
  4055. \@ifundefined{AmSTeX}
  4056.    {\def\AmSTeX{\leavevmode\hbox{$\cal A\kern-.2em\lower.376ex%
  4057.         \hbox{$\cal M$}\kern-.2em\cal S$-\TeX}}}{}
  4058. \@ifundefined{BibTeX}
  4059.    {\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em%
  4060.     T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{}
  4061. \@ifundefined{SliTeX}
  4062.    {\def\SliTeX{{\rm S\kern-.06emL\kern-.18em\raise.32ex\hbox
  4063.                 {\sc i}\kern -.03em\TeX}}}{}
  4064. %    \end{macrocode}
  4065. % \end{macro}
  4066. % \end{macro}
  4067. % \end{macro}
  4068. % \begin{macro}{\PlainTeX}
  4069. % \changes{v1.5g}{89/05/07}{space between plain and TeX changed.}
  4070. % \begin{macro}{\Web}
  4071. %     There's even a \PlainTeX{} and a \Web.
  4072. %    \begin{macrocode}
  4073. \@ifundefined{PlainTeX}{\def\PlainTeX{{\sc Plain}\kern2pt\TeX}}{}
  4074. \@ifundefined{Web}{\def\Web{{\sc Web}}}{}
  4075. %    \end{macrocode}
  4076. % \end{macro}
  4077. % \end{macro}
  4078. % \subsection{Changing the {\tt\protect\bslash catcode} of \%}
  4079. % \begin{macro}{\MakePercentIgnore}
  4080. % \begin{macro}{\MakePercentComment}
  4081. %    And finally the most important bit: we change the \verb+\catcode+
  4082. %    of `\verb+%+' so that it is ignored (which is how we are able to
  4083. %    produce this document!). We provide two commands to do the actual
  4084. %    switching.
  4085. %^^A The \verb+\MakePercentIgnore+ is then called as the
  4086. %^^A last command in this file.
  4087. %    \begin{macrocode}
  4088. \def\MakePercentIgnore{\catcode`\%9\relax}
  4089. \def\MakePercentComment{\catcode`\%14\relax}
  4090. %    \end{macrocode}
  4091. % \end{macro}
  4092. % \end{macro}
  4093. % \begin{macro}{\DocInput}
  4094. %    The two macros above are now used to define the
  4095. %    \verb+\DocInput+ macro which was introduced in version v1.5l
  4096. %    (or so) of
  4097. %    the {\tt doc} style option. In older versions
  4098. %    \verb+\MakePercentIgnore+ was placed at the very end of {\tt
  4099. %    doc.sty}.
  4100. %    \begin{macrocode}
  4101. \def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
  4102. %    \end{macrocode}
  4103. % \end{macro}
  4104. % We can now finish the {\tt docstrip} main module.
  4105. %    \begin{macrocode}
  4106. %</style>
  4107. %    \end{macrocode}
  4108. %  \begin{macro}{\on@line}
  4109. %    Finally something for people with an old \LaTeX:
  4110. % \changes{v1.7k}{92/08/24}{Macro and test added.}
  4111. %    \begin{macrocode}
  4112. \ifx\on@line\undefined
  4113.   \def\on@line{ on input line \the\inputlineno}
  4114.   \errhelp{Support for input line numbers has been added
  4115.            to latex.tex <dec91>.^^J^^J%
  4116.            Please update to a newer LaTeX release.}
  4117.   \errmessage{Obsolete LaTeX release (older than Dec.91)}
  4118. %    \end{macrocode}
  4119. %  \end{macro}
  4120. % \Finale
  4121. % \PrintIndex \PrintChanges
  4122. \endinput
  4123.